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Chapter 1 


Introduction 


Welcome to the SunCore graphics package and its Programmer’s Reference Manual. Sun 
Microsystems offers a comprehensive package of engineering graphics software providing the 
underlying support for interactive graphics applications programs. The SunCore software is an 
implementation of the ACM Core graphics specification^, plus extensions. SunCore is imple¬ 
mented to level 3C of the ACM Core specification for output primitives, and to level 2 of the ACM 
Core specification for input primitives. 

Extensions to the Core include textured polygon fill algorithms, raster primitives, rasterop attri¬ 
butes, shaded surface polygon rendering, and hidden surface elimination. 

This graphics package supports both the high resolution monochrome bitmap displays and the 
Sun color displays. Device-dependent routines support all these displays under SunCore. 

NOTE that this manual is a reference manual for the SunCore graphics package. It is not a 
tutorial for the programmer without knowledge of graphics principles. It assumes ttfat the 
reader is familiar with the concepts of graphics, and has some familiarity with the ACM Core 
specification. Those who are new to graphics should consult one of the publications listed in 
further reading at the end of this chapter. 


Where to Start 

If you are an applications programmer who is familiar with the ACM Core specification, but are 
new to SunCore, it is recommended that you read appendix A in order to become familiar with 
the areas where SunCore deviates from and provides extensions to the ACM Core specification. 

Note that SunCore supports the ACM Core output level 3C, that is, dynamic output is sup¬ 
ported, including two and three-dimensional translation, scaling, and rotation. SunCore sup¬ 
ports the ACM Core input level 2, that is, synchronous input, including the PICK device. Sun¬ 
Core supports dimension level 2, that is, three-dimensional operations. 


1.1. Overview and Terminology 

The objective of a graphics application program is drawing pictures and text on some display 
device, be it an ephemeral display device such as TV monitor or terminal, or a hard copy device 
such as a plotter or printer. 


^ As defined in Computer Graphics, the ACM SIQGRAPH Quarterly, Volume 13, #3, August 1979. 
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There is a need for a device-independent way of representing graphics images in the computer, 
and having a collection of software routines map the device-independent representations into the 
physical representations that the output device can handle, SunCore is an implementation of 
one of the “standard” packages of graphics software that have appeared recently. This section 
introduces some of the terminology of SunCore. This terminology is used throughout this 
manual. It is somewhat easier to describe the terminology from the point of view of the physical 
device working backwards to the application program, rather than starting at the software and 
working out to the device. 

There are two quite distinct points of view for looking at a system running a graphics applicar 
tion: 

• The physical device (monitor, printer, and so on) on which the final pictures appear, and 

• The internal world which the programmer uses to describe the pictures, and which (because of 
SunCore] is independent of the physical device. 

A view surface is a physical surface on which the final picture appears. 

There are two interdependent sets of coordinate systems in use in the graphics package: 

World Coordinates 

is a coordinate system which is device-independent. The applications programmer constructs 
all graphical objects in terms of world coordinates. 

Normalized Device Coordinates 

(often abbreviated to NDC) is a fixed coordinate system which is independent of physical out¬ 
put devices. World coordinates are transformed to normalized device coordinates for clip¬ 
ping and other operations. Each physical output device driver then transforms from iformal- 
ized device coordinates to the physical device coordinates for each view surface. 

A viewport is a region of NDC space which the programmer selects and on which the pictures will 
appear. 

It is the job of the viewing transformations to perform the correct mapping between world coor¬ 
dinates and normalized device coordinates. 

A window is a region defined in world coordinates within which the images that the application 
program defines appear. The selection of the coordinates for the window are arbitrary the 
graphics package maps the window into the viewport. 

In two dimensions, the transformation from the window to the viewport is a relatively straight¬ 
forward process. In three dimensions, another level of complexity is introduced with the notion 
of a view plane which is positioned arbitrarily in world coordinates. 

An output primitive^ or often just a primitive^ is a part of a picture (such as a line or a character 
string). The appearance of primitives (such as solid or dotted lines) is determined by primitive 
attributes. A primitive attribute is a general characteristic of an output primitive, and affects the 
appearance of that primitive. Examples of primitive attributes are color, linestyle, and 
linewidth. 

Each output primitive may be assigned a name, called the ptck-td, which is used to identify that 
primitive when an input operation (such as pointing at the primitive with the mouse) is applied. 

The Current Position is a SunCore system value that defines the current location for drawing. 
At startup time, the Current Position is set to the origin of the world coordinate system. Func¬ 
tions that create output primitives (move, line, and so on) can alter the Current Position. 
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Output primitives are collected together in segments. A segment defines an image which is a 
part of the picture on a view surface. 

Segments are divided into two classes, namely: temporary and retained, A retained segment has 
a name, and can have segment attributes associated with it. A temporary segment is nameless, 
and furthermore, the image that a temporary segment defines only remains visible as long as 
information is only being added to the view surface. As soon as a new frame action (one which 
repaints view surface) occurs, the temporary segment’s image disappears from the view surface. 

Each retained segment has one static attribute, its image transformation type. The value of this 
attribute can be none, translatable, or transformable. Translatable and transformable retained 
segments can be translated or transformed in either two or three dimensions. 

Segments also have dynamic attributes. The visibility and highlighting attributes control the 
appearance of the image. The detectability attribute determines if the segment can be detected 
by the pick device. Dynamic attributes for translatable and transformable segments include the 
segment’s image transformation. Depending on the image transformation type, the image 
transformation may contain translation, rotation, and scaling components. 

A vievoing operation is an operation that maps positions in world coordinates to positions in nor¬ 
malized device coordinates. The viewing operation also determines the portion of the world 
coordina-te space that is visible if window clipping or depth clipping is enabled. 

The applications program can obtain user interaction by means of input primitives, which pro¬ 
vide facilities for pointing at objects, entering data from the keyboard, and causing events. 


I. 1,1. Basics of Drawing Pictures 

The general sequence of actions that an application program goes through to create a picture on 

a device is this: 

1; Initialize SunCore. 

2. Initialize a view surface upon which the picture will be drawn. 

3. Select a view surface upon which the picture will be drawn. 

4. Specify the viewing operation parameters (sizes of windows in world coordinates, size of 
viewport, and so on). 

5. Set an image transformation type. 

6. Create a segment. The created segment becomes the currently open segment until it is 
closed. 

7. Set attributes for the segment, if required. 

8. Draw objects in the segment using output primitives. 

9. Close the segment. 

10. Repeat steps 4 through 9 as often as required, for as many segments as needed to build the 
picture. 

II. Apply image transformations (translation, scaling, and rotation) to a given segment, to 
achieve the required picture on the display device. 

12. Deselect the view surface. 
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13. Terminate SunCore. 

In providing the application programmer with the capabilities needed to draw pictures, Sun¬ 
Core breaks the interface into six functional areas: 

Control 

directs the major actions of SunCore, such as startup, shutdown, selection and deselection 
of view surfaces, and so on. 

Segments 

control the creation, closing, and removal of segments. Segments are then used to collect 
sets of: 

Output Functions 

also known as output primitives, which describe the drawing of lines and line sequences, 
shaded regions, text, and markers. 

Attributes 

control the way in which output primitives actually appear in the final image (solid or dotted 
lines, for instance). 

Transformations 

control the major appearances of pictures, such as orientation (rotation), scaling, and trans¬ 
lation. Transformations also control projection type and clipping. 

Input Functions 

handle the interaction with the user via the keyboard and the mouse. 


1.2. Getting Started With SunCore 

This section provides a very simple example of a SunCore application program. The program 
draws a martini glass on the screen. This program demonstrates the use of: 

• Creating a temporary segment (see Segmentation and Naming), 

• Moving to an absolute position (see Output Primitives), 

• Using the polyline drawing routines (see Output Primitives), 

• Using the absolute line drawing routines (see Output Primitives), 

The annotated code of glass.c is shown below, followed by the cc compiler call used to create the 
executable program. 

The first thing in the program is an include statement to get the definitions of constants: 

#include <usercore.h> 

Then there are the definitions of the relative points for the polyline function to draw the glass: 

static float glassdxH = {-10.0,9.0,0.0,-14.0, 30.0,-14.0,0.0, 9.0,-10.0>; 
static float glassdyf] = {0.0,1.0,19.0,15.0,0.0,-15.0,-19.0,-1.0,0.0}; 
int bwldd(); /* Device driver name for Sun-1 Monochrome */ 

/* display — see appendix B for details */ 
struct vwsurf vwsurf = DEFAULT_VWSURF (bwldd) ; 
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Then comes the main program with some initialization code: 

main () 

< 


/* First initiaiize the SunCore Package */ 
if (initialize_core(BASIC, NOINPUT, TWOD)) 
exit(1); 

/* Elements of vwsurf may be set up here */ 

/* See Appendix B for details */ 

/* Then initialize the monochrome display */ 
if (initialize_view_surface(fivwsurf, FALSE)) 
exit (2); 

/* Then we must select that view surface */ 
if (select_view_surface (fivwsurf)) 
exit (3); 

/* Then define the limits of the viewport */ 
set_viewport_2(0.125, 0.875, 0.125, 0.75); 

/* Then set a convenient window */ 
set_window(—50.0, 50.0, —10.0, 80.0); 

/* Create a temporary segment */ 
create_teiTiporary_segment 0 ; 




Here is the actual code that draws the picture: 

/* Now move to our origin point */ 

move_abs_2(0.0, 0.0); 

/* And draw the outline of the glass */ 
polyline_rel_2(glassdx, glassdy, 9); 

/* Then move to draw the liquid surface */ 

move_rel_2(—12.0, 33.0); 

/* Draw the liquid surface */ 

line_rel_2(24.0, 0.0); 

Finally, we close things and exit the program: 

/* Now close the segment */ 

close_teinporary_seginent 0 ; 

/* Wait for 10 seconds .... */ 

sleep(10); 

/* Before closing the view surface . */ 

deselect_view_sur face (fivwsur f) ; 

/* and closing down SunCore */ 

terminate_core (); 


Now we compile this program using the C compiler: 

tutorial% cc glass.c -Icore -Isunvlndow -Iplxrect -Im 

o 
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In the above example, the options: 

—Icore selects the SunCore run-time library from /u«r//i6/^*6corc.a, 

—Isunwindow selects the window system library, 

—Ipixrect selects the pixrect library, 

—Im selects the correct math library. 


When the compilation is complete, the final program is in the file a.out and may be run by typ¬ 
ing its name. 

This is, a very simple example, using the bare minimum of SunCore’s capabilities. There are 
many improvements that could be made, such as adding an olive on a cocktail stick and so on. 
The Programming Examples section of this manual will cover other areas of the graphics pack¬ 
age. 


1.3. The SunCore Lint Library 

SunCore provides a lint library which provides type checking beyond the capabilities of the C 
compiler. For example, you could use the SunCore lint library to check the martini-glass draw¬ 
ing program with command like this: 

tutorial% lint glass.e —Isuneore 

but note that the error messages that lint generates are mostly warnings, and may not neces¬ 
sarily have any effect on the operation of the program. For a detailed explanation of lint, see 
the lint manual in the Programming Tools manual. 


1.4. The Coordinate Systems 

Applications programs which draw pictures using SunCore communicate in world coordinates. 
World coordinates are a device-independent, two or three-dimensional, Cartesian coordinate sys¬ 
tem for describing objects. Output primitives are given to SunCore routines in World Coordi¬ 
nates (WC). However, if the world^coordinate matrix is used, SunCore concatenates this 
matrix with the view transform so that output primitives are first transformed by this matrix 
from ‘model’ or ‘object’ coordinates to world coordinates. This means that the user can supply 
primitives in ‘model’ coordinates, each model or object being moved into world coordinates 
according to the current world^coordinate_matrix. 

In three dimensions, the user may choose to use right-handed or left-handed world coordinates. 
In a right-handed system, if (for example) the x coordinate increases to the right and the y coor¬ 
dinate increases upwards, then the z coordinate increases towards the viewer. In the correspond¬ 
ing left-handed system, the x coordinate increases to the right, the y coordinate increases 
upwards, and the z coordinate increases away from the viewer. 

The composite viewing transform is formed from the world^coordtnate^matrix and the viewing 
parameters. SunCore routines transform the output primitives from world (or model) coordi¬ 
nates to Normalized Device Coordinates (NDC), which are a left-hand coordinate system 
bounded such that: 0 . 0 < 2 ,i^, 2 < 1.0 


1-6 


Revision F of 15 May 1985 







SunCore Reference Manual 


Introduction 


Since current Sun view surfaces have four-to-three aspect ratios, the default normalized device 
coordinate space has the y extent bounded to 0.0<j/<0.75. Primitives are stored in the Display- 
List (also called the Pseudo Display File or PDF), in Normalized Device Coordinates. The user- 
specified window in world coordinates is mapped (and optionally clipped) to the user-specified 
viewport within normalized device coordinate space. The entire normalized device coordinate 
space is then mapped to the selected physical view surfaces. 

1.5. Details of Using SunCore 

This section describes the details of creating applications programs to run with SunCore. 


L5.1. Classification of Functional Capabilities 

The ACM Core specification defines levels of functional capability for a graphics package which 
implements the specification. The table below shows the classification. Terms such as BUFFERED 
and DYNAMICA are defined as constants in the file usercore.h, discussed below. 

Table 1-1: Output Capabilities 




Output Capabilities 



Functional Capability 

BASIC 

BUFFERED 

DYNAMICA 

DYNAMICB 

DYNAMICC 

Output Primitives and 
Primitive Attributes. 

yes 

yes 

yes 

yes 

yes 

Viewing 

yes 

yes 

yes 

yes 

yes 

Control 

yes 

yes 

yes 

yes 

yes 

Temporary Segments 

yes 

yes 

yes 

yes 

yes 

Retained Segments 

no 

yes 

yes 

yes 

yes 

Highlighting Segment 
Attribute 

no 

yes 

yes 

yes 

yes 

Visibility Segment 
Attribute 

no 

yes 

yes 

yes 

yes 

Image Transformation 
Segment Attribute 

no 

no 

yes 

yes 

yes 

Detectability Segment 
Attribute 

no 

* 

yes 

♦ 

yes 

* 

yes 

♦ 

yes 


• This feature is only available if input levels SYNCHRONOUS or COMPLETE are supported. Note 
that SunCore supports all output levels up to DYNAMICC. 
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Table 1-2: Input Capabilities 


Functional Capability 

Input Capabilities 

NOINPUT 

SYNCHRONOUS 

COMPLETE 

Device Initialization and Termination no 

yes 

yes 

Synchronous Interaction Functions 

no 

yes 

yes 

Echo Control 

no 

yes 

yes 

Explicit Enable or Disable 

no 

no 

yes 

Event Queue Management 

no 

no 

yes 

Sampled Device Functions 

no 

no 

yes 

Associations 

no 

no 

yes 


Note that SunCore supports up to the SYNCHRONOUS input level. 


Table 1-3: Dimension Levels Supported 


Dimension Levels Supported 


Functional Capability 

TWOD 

THREED 

Two Dimensional Primitives, 
Attributes, and Viewing. 

yes 

yes 

Three Dimensional Primitives, 
Attributes, and Viewing. 

no 

yes 


Note that SunCore supports the THREED dimension level. 


1.5,2. Error Reporting 

SunCore performs consistency checks on arguments passed to its various routines. Any time an 
error is detected, the name of the routine which raised the error condition and the text of the 
error message are printed on the standard error (stderr). 

All SunCore interfaces are functions that return a value. If a function completes successfully, it 
returns the value zero. If the function raises any error conditions, it returns a non-zero value. 
SunCore always identifies the name of the routine which raised the error condition. The ACM 
Core specification defines specific error numbers. These do not correspond to SunCore’s error 
numbers in the current release. 
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1.5.3. Useful Constants in the usercore.h Include File 

The file usercore.h defines a collection of constants which the application programmer should use 
in lieu of hardwired constants in code. The constants are described here (but their values are 
not stated). 

Useful Constants: 

TRUE A universal value denoting the truth value. 

FALSE A universal value denoting the false value. 

MAXVSURF The maximum number of view surfaces which may be initialized at any one time. 

Initialization Constants. These constants describe the levels of the SunCore facilities which the 
application program will use. These constants should be used when calling the initializ€_core 
function. 

BASIC Denotes the basic output level. See the tables above for the classifications. 

BUFFERED Denotes the buffered output level. See the tables above for the classifications. 

DYNAMICA Indicates that the application package wishes to use two-dimensional translation facil¬ 
ities. See the tables above for the classifications. 

DYNAMICS Indicates that the application package wishes to use two-dimensional scaling, rota¬ 
tion, and translation facilities. See the tables above for the classifications. 

DYNAMICC Indicates that the application package wishes to use three-dimensional scaling, rota¬ 
tion, and translation facilities. See the tables above for the classifications. 

NOINPUT Indicates that this application package will not use any input facilities. See the 
tables above for the classifications. 

SYNCHRONOUS 

Indicates that this application program will use synchronous input facilities. See the 
tables above for the classifications. 

COMPLETE SunCore does not support this input level. See the tables above for the 
classifications. 

TWOD Indicates that the application package will only use two-dimensional functions. See 
the tables above for the classifications. 

THREED Indicates that the application package will use both two-dimensional and three- 
dimensional functions. See the tables above for the classifications. 

Character Quality Constants. These constants should be used when calling the set^charprecision 
function. 

STRING Denotes low quality text. 

CHARACTER 

Denotes medium quality text. 

Transform Constants. These constants should be used when calling the $et_profection and 
set^coordinate^system^type functions. 
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PARALLEL Value to indicate parallel projection. 

PERSPECTIVE 

Value to indicate perspective projection. 

RIGHT Value to indicate right-handed world coordinate system. 

LEFT Value to indicate left-handed world coordinate system. 

Image Transformation Type Constants. These constants are used when calling the 
set_image^transformationjtype and set_segment_image.^transformation_type functions. 

Indicates a retained segment which cannot be transformed. 

Indicates a retained segment which may be translated in two dimensions. 

Indicates a retained segment which may be fully translated, scaled, and rotated, in 
two dimensions. 

Indicates a retained segment which may be translated in three dimensions. 

Indicates a retained segment which may be fully translated, scaled, and rotated, in 
three dimensions. 

Line Style Constants. These constants should be used when calling the setjlinestyle attribute for 
output primitives, 

SOLID Solid line. 

DOTTED Dotted line. 

DASHED Dashed line. 

DOTDASHED 

Dashed and dotted line. 

Text Font Selection Constants. These constants should be used when calling set_font. 

ROMAN For character precision, a Roman font; for string precision, a raster font. 

GREEK For character precision, a Greek font; for string precision, the default raster font. 

SCRIPT For character precision, a Script font; for string precision, a small raster font. 

OLDENGLISH 

For character precision, an Old English font; for string precision, equivalent to 
ROMAN. 

STICK For character precision, a stick font; for string precision, equivalent to GREEK. 
SYMBOLS For character precision, a set of symbols; for string precision, equivalent to SCRIPT. 

Input Device Constants. These constants should be used when calling the initialize^device and 
terminate_device functions and other input functions. 

PICK The Pick device. The mouse in SunCore. 

KEYBOARD The Keyboard device. 


NONE 

XLATE2 

XF0RM2 

XLATE3 

XFORM3 
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STROKE The freehand stroke device. The mouse in SunCore. 

LOCATOR The Locator device. The mouse in SunCore. 

VALUATOR The Valuator device. The mouse in SunCore. 

BUTTON The Button device. The mouse in SunCore. 

RasterOp Constants. These constants should be used when calling the s€t_rasterop function. 
NORMAL Indicates normal copy mode. 

XORROP Indicates bitwise exclusive or of source and destination. 

ORROP Indicates bitwise or of source and destination. 

Polygon Rendering Style Constants. These constants should be used when calling the 
set_polygon_interior_style and set_shading^parameters functions. 

PLAIN Indicates area fill with the color indicated by the fill index primitive attribute. 

SHADED Indicates shading according to the current shading parameters (for 3-D polygons 
only). 

CONSTANT Indicates constant user-specified shade. 

GOURAUD Indicates Gouraud shading. 

PHONG Indicates Phong shading. 

1*6. Further Reading 

J. D. Foley and A. Van Dam: 

Fundamentals of Interactive Computer Graphics, Addison-Wesley, 1982. 

W. M. Newman and R. F. Sproull: 

Principles of Interactive Computer Graphics (2nd edition), McGraw-Hill, 1979. 

ACM SIGGRAPH: 

Conference Proceedings. 

IEEE Computer Graphics and Applications Magazine 

Computer Graphics ACM SIGGRAPH Quarterly, Vol 13, ^3, August 1979 
Status Report of the Graphics Standards Planning Committee. 

ACM Computing Surveys, Vol 10, Dec 1978 
Special Issue on Graphic Standards. 

Computer Graphics World, Vol 5, #8, August 1982 
The SIGGRAPH Core System Today. 
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Chapter 2 
Control 



The SunCore graphics package provides several functions for controlling the system. These 
functions are discussed here, and the sections and subsections which follow describe the indivi¬ 
dual functions in detail. 

Initialization and termination 

of SunCore provide for the initialization of the package to a specific and predetermined 
state, and for closing it down when the applications program has finished using the graphics 
package. 

View surface control 

provides for the initialization, termination, and selection of view surfaces. A view surface 
must be initialized before it can be used. A view surface should be terminated when the 
applications package has finished with it. Functions are provided to add view surfaces to the 
set of selected view surfaces, and to remove view surfaces from that set. View surface names 
in SunCore are structures. The vwsurf structure is declared in usercore.h and is 
described in appendix B. SunCore supports several view surfaces to date; see appendix B 
for details of view surfaces. 

Picture change control 

provides for the “batching” of changes to dynamic segment attributes so that the application 
program may force the simultaneous occurrence of a group of changes. 

Frame control 

denotes the function called new_frame, which clears the view surface and redraws all seg¬ 
ments except temporary segments. 

Error handling 

is that part of SunCore concerned with reporting errors to the application program. 


2.1. Initialization and Termination 

There are two functions provided for initializing and terminating SunCore. The application 
program should call initialize_core before making any other calls upon the graphics sys¬ 
tem. terminate„core should be the last call to SunCore before the application program 
itself is finished. 
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2.L1. initial ize_core — Initialize the SunCore System 
initializo^core initializes the Core graphics package to a known state, 
initia1ize_coro(output_level, input_levol, dimension) 


int 

output_levol; 

/* 

SunCore Level for Output 

V 



/* 

BASIC, BUFFERED, DYNAMICA 

V 



/* 

DYNAMICB, DYNAMICC 

V 

int 

input_level; 

/* 

SunCore Level for Input 

V 



/* 

NOINPUT, SYNCHRONOUS, COMPLETE 

V 

int 

dimension; 

/* 

Number of Dimensions Required 

V 



/* 

TWOD, THREED 

V 


SunCore supports up to output level DYNAMICC of the ACM Core specification, up to input level 
SYNCHRONOUS of the ACM Core, and dimension level THREED of the ACM Core. 

Errors returned from initialize_core: 

• The SunCore system is already initialized. 

• The specified output level cannot be supported. 

• The specified input level cannot be supported. 

• The specified dimension cannot be supported. 

2.1.2. terininate_core — Close Down the SunCore System 
t:erminate_core closes down the Core graphics package. 
terminate_core () 


2.2. Initializing and Selecting View Surfaces 

View surface control provides for the initialization, termination, and selection of view sur¬ 
faces. A view surface must be initialized before it can be used. A view surface should be ter¬ 
minated when the applications package has finished with it. Examples of view surfaces are the 
Sun color display and the Sun monochrome bitmap display. Functions provided in this category 
are: 

initialize_view_surface 

performs the functions required to gain access to a specified view surface. 

terminate_view_sur face 

terminates access to the specified view surface. 

select_view_surface 

adds the specified view surface to the set of selected view surfaces for output. 
deselect_view_sur face 

removes the specified view surface from the set of selected view surfaces. 
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in(juire_select:ed_sur faces 

determines which view surfaces are currently selected (not yet implemented). 


2.2.1. initialize_view_surface — Initialize a View Surface 

initialize_view_surface initializes the Core package for a specific view surface. 

initialize_view_surface(surfac 0 _namo, type) 

struct vwsurf *sur face_naiiio; /* See appendix B */ 

int type; /* TRUE for hidden surface removal */ 

/* FALSE otherwise */ 

The surface_name argument to the function specifies a physical view surface. View surface 
names in SunCore are structures. The vwgurf structure is defined in the usercore.h header file. 
Only color devices support hidden-surface removal. 

Errors returned from initialize_view_surface: 

• The view surface specified by surface_name is already initialized. 

• The view surface specified by surface_name does not have any output device associ¬ 
ated with it, 

• No other view surfaces can be initialized at this time. 

• The specified view surface does not support hidden surface removal. 

2.2.2. t:erminate_view_surface — Close Down a View Surface 

terminato_view_sur face closes down the specified view surface. 

terminate_view_surface(sur face_name) 

struct vwsurf *surface_naiiie; /* See appendix B */ 


Errors returned from terminate_view_sur face; 

• The view surface specified by surface_naiiie is not initialized. 

2.2.S. select_view_sur face —Add View Surface to Selected Set 

select^view^sur fac© adds a specified view surface to the list of selected view surfaces. 

select_view_sur face(sur fac©_namo) 

struct vwsurf *surface_naino; /* See appendix B */ 

A segment is only drawn on those view surfaces marked as “selected” at the time that the seg¬ 
ment is created. 


Errors returned from select_view_surface: 
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• A segment is open. 

• The view surface specified by surface_namo is not initialized. 

• The view surface specified by sur face_nanie is already selected. 

• The view surface specified by surface_name cannot be selected. 


2.2.^. deselect_view_sur face — Remove View Surface from Selected Set 

deselect:_view_surface removes a specified view surface from the list of selected view sur¬ 
faces. 


d[eselec't_view_surface (sur face_name) 

struct vwsurf *surface_naiiie; /* See appendix B */ 

Segments created after deselect;_view_sur face is called will not be drawn on the 
deselected view surface. 


Errors returned from deselect_view_surface: 

• A segment is open. 

• The view surface specified by surface_name is not selected. 


2.3. Batching of Updates 

SunCore provides the facility for the application program to indicate that a sequence of updates 
is being started, and the graphics package stacks up these picture changes until an 
end_batch_of_updat:es function call indicates that the end of the sequence of updates ha.s 
occurred. Picture changes or ‘updates’ include dynamic segment attributes such as visibility, 
detectability, translate, rotate, and scale. 


2.3.1, begin_batch_of_updates — Indicate Start of a Batch of Updates 

begin_bat:ch_of_updat:es indicates the beginning of a batch of updates to the picture. All 
modifications to dynamic attributes of segments between calls to begin_batch_of_updates 
and erid_batch_o f^updates are saved up and executed simultaneously. 

begin_batch^of_updates () 


Errors returned from begin_batch_of_upda'tes: 

• There has been no end_batch_of_updates function call since the last 
begin_batch_of_updates function call. 
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2.3,2. end_batch_of_updates — Indicate End of a Batch of Updates 

end_batch_of_updates indicates the end of a batch of updates. The batch of changes to 
dynamic attributes of segments is executed, 

end_batch_of_updates() 


Errors returned from end_batch_of_upda'tes: 

• There has been no corresponding begin_batch_of_updates function call. 


2.4. Frame Control 


new_frame — Start New Frame Action for Selected View Surfaces 

new_frame starts new frame action for currently selected view surfaces. The view surface is 
cleared, and all visible retained segments are redrawn. 

new_frame() 


Errors returned from new^frame: 

• The set of currently selected view surfaces is empty. 


2.6. Error Control 


2.5.1. report_most_recent_error 

report_most_recent_error obtains a copy of the most recently detected error number. 

report:_most_recent_error (©rror_nuinber) 
int *error_number; 

A value of zero returned to error_nuinber indicates that there has been no error since the 
last call on report:_most:_recent;_error. 


2.5.2. print_error 

To print the message associated with this error_number on the standard error file (stderr), 
use the function call: 
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print_error (”Your mess age, error_number) ; 
int error_nuniber; 

where “Your message” is any character string that the user wants printed. The error message is 
printed on the line following “Your message”. 


2.6. Drag Control (SunCore Extension) 


2.6.1. set_drag 

An additional function, se't_dlrag, writes all output to the bitmap or color framebuffer with 
exclusive or’ing. 

set_drag(mode) 

int mode; /* FALSE = uses the rasterop */ 

/* set by set_rasterop */ 

/* TRUE = enable XOR*ing */ 

If dragging is enabled, all output to the device drivers is done with exclusive OR’s to the data in 
the displays. This feature makes dragging more convenient. For example, if you want to drag 
segment A across segment B, leaving segment B’s image unaffected, do the following sequence of 
operations: 

• Set A visibility off, 

• Set dragging on, 

• Set A visibility on, 

• Drag segment A to the desired location, 

• Set A visibility off, 

• Set dragging off, 

• Set A visibility on. 

See also: set_rasterop. 
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Viewing Operations and Coordinate Transforms 


Specifying a viewing operation may be thought of as specifying the arbitrary orientation of a syn¬ 
thetic camera. The resulting view of the object (the snapshot) can appear on one or more view 
surfaces. The viewing operations are provided for two reasons: 

1. To specify how much of the world coordinate space should be visible, and 

2. To specify a mathematical transformation between the world coordinate system and the nor¬ 
malized device coordinate system. 

A viewing operation is specified by a view volume that defines the portion of world coordinate 
space which is to be projected onto a view plane (also called a projection plane), and a rectangu¬ 
lar viewport in normalized device coordinate space to which the projected image will be mapped. 
The viewing operation is sufficiently general as to support both parallel and perspective projec¬ 
tions. The parallel projection includes the orthographic, axonometric, Isometric, cavalier, and 
cabinet projections, as special cases. 

Once the camera model is specified via calls to set_view_reference_poin't, 
se't_view_plane_normal, and so on, a 4 X 4 view transform matrix is constructed. Then the 
process of generating an image on a view surface is: 

1. View-transforming the output primitives (using the view transform preceded by any model¬ 
ling transform the user has specified) to normalized device coordinates. 

2. Optional clipping to the window. 

3. Scale the output to map the window to the viewport. 

4. Optional image transformation as specified by dynamic segment attributes. 

5. Optional clipping to the viewport. 

6. Convert to device coordinates and draw the picture. 


3.1. Windows, View Volumes, and Clipping 

The window is the bounded portion of the view plane containing projected objects which will 
appear within the viewport on the view surface. The view surface corresponds to the physical 
device on which the picture is drawn. The window is the logical region, specified in world coor¬ 
dinates, in which the image appears. 

Specifying a window involves defining a coordinate system for the view plane. The coordinate 
system for the view plane is called the UVW coordinate system, to distinguish it from the world 
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coordinate system and the normalized device coordinate system, both of which are XYZ coordi¬ 
nate systems. 

The origin of the UVW coordinate system is at the point where the line through the view refer¬ 
ence point parallel to the view plane normal vector intersects the view plane. In the default 
case, the view plane distance is zero, and so the view reference point lies in the view plane and is 
the origin of the UVW coordinate system. 

The direction of the V axis is determined from the view up vector. The view up vector is 
specified in world coordinates relative to the view reference point. 

The positive U axis of the UVW coordinate system is 90 degrees clockwise from the positive V 
axis, as viewed in the direction of the view plane normal vector. The positive U and V axes, 
together with the view plane normal vector, form a left handed coordinate system. The window 
is specified in terms of maximum and minimum « and v values (see the set_window function). 

The diagram below shows the various components of the viewing system. 


Front 

Clipping Plane 



Projection 


Figure 3-1: Components of Viewing System 
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3.2. Default Values of Viewing Operation Parameters 


Table 3-1: Default Values of Viewing Operation Parameters 


Parameter 

Viewing Operation Parameters 

Default Value 

View Reference Point 

(0, 0, 0) 

View Plane Normal 

(0,0, -1) 

View Distance 

0 

Front Distance 

0 

Back Distance 

1 

Type of Projection 

Parallel {0, 0, 1) (perpendicular to the UV plane) 

Window 

(0, 1, 0, 0.75) 

View Up Vector 

(0, 1, 0) 

Normalized Device 

0.0<2,2<1.0 

Coordinate Space 

0.0<y<0.75 

Viewport 

(0.0, 1.0, 0.0, 0.75, 0.0, 1.0) 


Table 3-2: Default Values of Viewing Control Parameters 


Parameter 

Viewing Control Parameters 

Default Value 

Window Clipping 

On 

Output Clipping 

Off 

Front Plane Clipping 

Off 

Back Plane Clipping 

Off 

World Coordinate System 

Right handed 
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Table 3-3: World Coordinate Matrix Parameters 


World Coordinate Matrix Parameters (Modelling Transform) 

Parameter 

Default Value 


1000 

World Coordinate Matrix 

(identity) 

0 0 10 


000 1 


Table 3-4: Image Transformation Parameters 


Parameter 

Image Transformation Parameters 

Default Value 

SX, SY, SZ 

1, 1, 1 (no scaling) 

AX, AY, AZ 

0, 0, 0 (no rotation) 

TX, TY, TZ 

0, 0, 0 (no translation) 


3.3. Setting 3D Viewing Operation Parameters 

SunCore provides a number of functions for setting parameters of the viewing operations. 
There are a number of separate calls available for setting individual parameters, then there is a 
composite set_viewing_paranio'ters function which sets all the viewing parameters in one 
fell swoop. The individual calls provided are summarized here and described in detail in the sub¬ 
sections following. 
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Table 3-5: Summary of Functions for Setting Viewing Control Parameters 


Function 

Description 

fiot^vlew^roferonco_poInt 

Sets the view reference point in world coordinates. 

5et_view^l ane^norma 1 

Defines a vector which determines the view plane, rela¬ 
tive to the view reference point. 

6et_vlew^lane_dlstanco 

Defines the view plane distance from the view reference 
point along the view plane normal vector. 

sot_vlow_depth 

Defines the distance from the view reference point to 
the ‘front’ clipping plane (also known as the ‘hither’ or 
‘near’ clipping plane) and the distance from the view 
reference point to the ‘back’ clipping plane (also known 
as the ‘yon’ or ‘far’ clipping plane). 

sot^r o j ect Ion 

Selects perspective or parallel projection, and defines 
the center of projection (for PERSPECTIVE projection) 
or direction of projection (for PARALLEL projection). 

set_viow^up_2, fiGt_viow_up_3 

Establish the view up direction in the view plane for 
two or three-dimensional viewing. 

sot:_wlndow 

Establishes the window boundaries in the view plane. 

SGt_viowport_2, s©t_vi0vport_3 

Establish the viewport boundaries in normalized device 
coordinates for two or three-dimensional viewing. 

SGt_ndc_spaco_2, set_ndc_spaco_3 

Establish the size of Normalized Device Coordinate 
space for two or three-dimensional viewing. 

sot_v lew lng_par amo-tor s 

is a composite function which does all of the above 
functions at one time. 


None of the above calls have any effect until the next call upon the 
creat;e_retained_segment or creat:e_tGmporary_segment: functions. 


S.3.1, set_view_reference_point —Establish Reference Point for Viewing 

set_view_reference_point sets the view reference point in world coordinates. 

,set_view_reference_point(x, y, z) 

float X, y, z; /* x, y, and z coordinates */ 

z, y, and z are the coordinates of the view reference point. In the absence of a specified refer¬ 
ence point, the default view reference point is (0, 0, 0). The new reference point does not take 
effect until a new segment is created. 
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3.3.2. set_view_plane_normal — Establish View Plane Normal Vector 

set_view_plane_normal defines a vector relative to the view reference point, in world coor¬ 
dinates. 


set_view_plano_noriiial (dx_norm, dy_norm, dz_norm) 
float dx_norm, dy_norm^ dz_norni; 

The view plane is perpendicular to the view plane normal vector. In the absence of any informa¬ 
tion to the contrary, SunCore establishes the view plane normal vector as (0, 0, —1). The new 
vector does not take effect until a new segment is created. 

Errors returned from set_viow_plane_normal: 

• No view plane normal direction can be established because dz_norm, dy_norm, and 
dz^norm are all zero. 


3.3.3. set_view_plane_distance — Establish View Plane Distance 
set_view_plane_distarace establishes the view plane distance. 

set_view_plane_distance(distance) 
float distance; 

set_viow_plane_distanco establishes the view, or projection, plane. The view plane is per¬ 
pendicular to the view plane normal vector, and is distance from the view reference point along 
the view plane normal vector. Distances are measured in world coordinate units from the view 
reference point. Positive values of distance correspond to the direction of the view plane normal 
vector, and negative values correspond to the opposite direction. In the absence of any informa¬ 
tion to the contrary, distance is set to zero, which means that the viewing plane is located at the 
view reference point. 


3 . 3 . 4 . set_projectiori — Select Projection Type 

set_projection selects the projection system for displaying. 

set_projection(projection, dx_proj, dy_proj, dz_proj) 
int projection; /* Projection typo */ 

/* PARALLEL ,* PERSPECTIVE */ 
float dx_proj, dy_proj, dz_proj; 

/* X, y, and z Deltas of Projection Point */ 

The arguments dx_proj, dy_proj^ and dz_proj specify a world coordinate point relative to the 
view reference point. If projection is PARALLEL, objects project onto the view plane along lines 
parallel to the vector specified by dx^proj, dy^proj, and dz_proj. If projection is PERSPECTIVE, 
(rfz_pro/, dy_proj, dz_prof) specify a point in world coordinates called the center of projection 
(often abbreviated to COP). Objects project onto the view plane along lines travelling towards 
this point. Thus the center of projection is the apex of a pyramid whose edges pass through the 
four corners of the view window. 

Errors returned from set_prejection: 
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• The direction of projection cannot be established because dz, dy, and dz are all zero. Note 
that this error is only applicable if parallel projection was selected. 


3 .3.5. set_view_up_2 —Establish 2D View Up Vector 

set_view_up_2 establishes a view up vector in two dimensions. This vector defines the direc¬ 
tion of ‘up’ for the window in world coordinates. 

set_view_up_2(dx, dy) 

float dx, dy; /* dx and dy coordinates */ 

Errors returned from set_view_up_2: 

• The view up vector cannot be established because dx, and dy are both zero. 


3 .3.6. set:_view_up_3 —Establish 3D View Up Vector 

set_view_up_3 establishes a view up vector in three dimensions. 

s et_view_up_3(dx_up, dy_up, dz_up) 
float dx_up, dy_up, dz_up; 

/* X. y, and z Deltas of View Up Vector */ 

The three arguments dx_up, dy^up, and dz_up establish a view up vector relative to the view 
reference point. The view up vector, when projected onto the view plane in the direction of the 
view plane normal vector, specifies the positive V-axis of the UVW coordinate system in the view 
plane. The U-axis is also in the view plane, such that the U-axis, the V-axis, and the view plane 
normal vector form a left handed coordinate system. The V-axis is vertical and the U-axis 
increases to the right when the view plane is mapped onto the view surface. 

SunCore establishes the default view up vector as (0, 1, 0), which means that the Y-axis is up. 

If the view plane normal vector is parallel to the Y-axis, this does not work and so SunCore 
checks the view transforms for validity when creating a segment. SunCore may generate the 
error message: 

'The current viewing specification is inconsistent* 

Errors returned from set_view_up_3: 

• No view plane normal direction can be established because dx_up, dy_up, and dz^up are 
all zero. 


3.3.7. set_ndc_space_2 — Establish Size of NDC Space 

set_ndc_space_2 defines the size of the Normalized Device Coordinate space which can be 
addressed on the view surface of all display devices available to the applications program and 
within which viewports may be established. 
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set_ndc_space_2 (width, height) 
float width, height; 

Both width and height must be in the range of 0.0 to 1.0, and at least one of the parameters must 
have a value of 1.0. Normalized Device Coordinates range from 0.0 to width in the horizontal 
direction and from 0.0 to height in the vertical direction. The rectangle defined by this function 
is mapped to the viewable area of any display device available to the application program so that 
the entire rectangle is visible. Only uniform scaling of the rectangle is allowed; no changes can 
be made to the viewport aspect ratio. SunCore maximizes the usable area of the dislay and 
centers NDC space on each view surface. 

The default Normalized Device Coordinate specification is iCTdfA=1.0 and height=0.75. Either of 
the set_ndc_space_2 or set_ndc_space_3 (see below) functions may be used at most 
once per initialization of SunCore, and the Normalized Device Coordinate space established 
applies to all view surfaces which the application program might use. 

Ten SunCore functions require that Normalized Device Coordinate space be established before 
they complete execution. If Normalized Device Coordinate space has not been explicitly defined 
before any of these functions are executed, they implicitly define the Normalized Device Coordi¬ 
nate space using default values. Functions which implicitly define Normalized Device Coordinate 
space are: 

• initialize_device 

• initialize_group 

• create_ret:ained_segment: 

• create_'temporary_segmen't 

• set_viewport_2 

• set:_viewport_3 

• set_viewing_parainet:ers 

• incpiire_viewport_2 

• inquire_viewport_3 

• inq{uire_viewing_paraineters 

The depth of Normalized Device Coordinate space is set to 0.0 if set_ndc_space_2 is used in 
a three-dimensional implementation. 


Errors returned from se-t_ndc_space_2: 

• sot:_ndc_space_2 or set:_ndc_space_3 has already been called since the system was 
initialized. 

• set_ndc^space_2 or set_ndc_space_3 has been called too late — the default 
values have already been defined implicitly. 

• A parameter is outside the range 0.0 to 1.0. 

• One of ividth or height must have a value of 1.0. 

• width or height has a value of 0.0. 
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3.3.8. set_ndc_space_3 — Establish Size of NDC Space 

set:_ndc_space_3 defines the size of the Normalized Device Coordinate space which can be 
addressed on the view surface of all display devices available to the applications program and 
within which viewports may be established. Three-dimensional Normalized Device Coordinate 
space is a rectangular parallelepiped lying within the Normalized Device Coordinate system. 
This coordinate system is always left-handed, with the :r-axis increasing to the right, the y-axis 
increasing upwards, and the 2 -axis increasing away from the viewer. 

. set_ndc_spac©_3 (width, height, depth) 
float width, height, depth; 

All of the parameters width, height, and depth must be in the range of 0.0 to 1.0, and at least one 
of width or height must have a value of 1.0. Normalized Device Coordinates range from 0.0 to 
width in the horizontal direction, from 0.0 to height in the vertical direction, and from 0.0 to 
depth in the direction away from the viewer. The rectangle of size width by height in the 2^0 
plane of Normalized Device Coordinate space is mapped to the viewable area of any display dev¬ 
ice available to the application program so that the entire rectangle is visible. Only uniform 
scaling of the rectangle is allowed — no changes can be made to the viewport aspect ratio. Sun- 
Core maximizes the usable area of the display and centers NDC space on each view surface. 

The default Normalized Device Coordinate specification is width=l.0, height=0.7S, and 
depth^l.O. Either of the sot_ndc_spaco_3 or set:_ndc_space_2 (see above) functions 
may be used at most once per initialization of SunCore, and the Normalized Device Coordinate 
space established applies to all view surfaces which the application program might use. 

Ten SunCore functions require that Normalized Device Coordinate space be established before 
they complete execution. If Normalized Device Coordinate space has not been explicitly defined 
before any of these functions are executed, they implicitly define the Normalized Device Coordi¬ 
nate space using default values. Functions which implicitly define Normalized Device Coordinate 
space are: 

• initialize_device 

• initialize_group 

• creat©_ret:ained_seginent 

• creat©_temporary_segment: 

• set:_;.viewport:_2 

• set_viewport_3 

• set_^viewing_parame'ters 

• incpjiire_viewport_2 

• inquire_viewport„3 

• inquire_viewing_parameters 


Errors returned from set:_ndc_space_3: 

• set_ndc_space_2 or set:_ndc_space_3 has already been called since the system was 
initialized. 

• set:_ndc_space„2 or set:_ndc_space_3 has been called too late — the default 
values have already been defined implicitly. 
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• A parameter is outside the range 0.0 to 1.0. 

• One of width or height must have a value of 1.0. 

• width or height has a value of 0.0. 


S.3.9. set_window — Establish a Window in the View Plane 

set_window establishes a window, defined by four coordinates in the UV coordinate system, in 
the view plane. 

set_window(umin, umax, vmin, vmax) 

float umin, Umax; /* Left and Right sides of window */ 

float vmin, vmax; /* Bottom and Top of window */ 

SunCore establishes the default window as (0.0, 1.0, 0.0, 0.75). 

Errors returned from set_window: 

• umin is greater than or equal to umaz, which means that the left side of the window is 
congruent with or to the right of the right side of the window. 

• vmin is greater than or equal to vmaz, which means that the top of the window is 
congruent with or below the bottom of the window. 


3.8.10. set_view_depth — Specify Planes for Depth Clipping 

set_view_depth defines the front and back planes for depth clipping. 

set„view_depth (fron1:_distance, back_distance) 
float front_distance, back_distance; 

/* Distances to Front and Back Planes */ 

Clipping to these depth bounds is controlled by set_front_plane_clipping and 
set_back_plane_clipping. The front and back planes determine the 3-D view volume 
which is mapped to the 3-D viewport. 

SunCore initializes the front distance to 0.0 and the back distance to 1.0. 

Errors returned from set_view_depth: 

• front^dtstance is greater than back^distance, so that the back clipping plane is in front of 
the front clipping plane. 


3 .3.11. set_viewport_2 — Establish Limits of Two-Dimensional Viewport 

set:_viewport_2 establishes the limits of the viewport in two-dimensional normalized device 
coordinate space. The limits must lie in the range: 0<x<NDCwidth and 0<y<NDCheigkt 

set_viewport_2(xmin, xmax, ymin, ymax) 

float xmin, xmax; /* Left and Right sides of Viewport */ 

float ymin, ymax; /* Bottom and Top of Viewport */ 
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SunCore establishes the viewport to (0.0, 1.0, 0.0, 0.75) at initialization time. 

Errors returned from set_viewport_2: 

• xmin is greater than or equal to xmax, which means that the left side of the viewport is 
congruent with or to the right of the right side of the viewport. 

• ymin is greater than or equal to ymax, which means that the top of the viewport is 
congruent with or below the bottom of the viewport. 

• Viewport exceeds Normalized Deviced Coordinate space. 


3.3.12, set:_viewport:_3 — Establish Litnits of Three-Dimenstonal Viewport 

se-t_viewport:_3 establishes the limits of the viewport in three-dimensional normalized device 
coordinate space. The limits must lie in the range: 0<x<NDCwidtk,(iKy<.NDCkeigkt, and 
0<z<iNDCdepth 

set_viewport_3(xmin, xmax, ymin, ymax, zmin, zmax) 

float xmin, xmax; /* Left and Right sides of Viewport */ 

float ymin, ymax; /* Bottom and Top of Viewport */ 

float zmin, zmax; /* Front and Back of Viewport */ 

SunCore establishes the viewport to (0.0, 1.0, 0.0, 0.75, 0.0, 1.0) at initialization time. 

Errors returned from set_viewport_3: 

• xmin is greater than or equal to xmaXf which means that the left side of the viewport is 
congruent with or to the right of the right side of the viewport. 

• ymin is greater than or equal to ymax, which means that the top of the viewport is 
congruent with or below the bottom of the viewport. 

• zmin is greater than or equal to zmax, which means that the front of the viewport is 
congruent with or behind the back of the viewport. 

• Viewport exceeds Normalized Deviced Coordinate space. 


'^.8.13. set_viewing_parameters 

set_viewing_parameters specifies all the viewing parameters with a single function call. 
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set_vlewing^arameters {view_ 4 )aranioters) 


struct •{ 

float vwrefptfS]; /* 
float vvplnorm[3]; /* 
float viewdis; /* 

float frontdis; /* 
float backdis; /* 

int projtype; /* 

float projdir[33; /* 

float window[4]; /* 

float vwupdir[3]; /* 

float viewport [6]; /* 
} *view_parameters; 


X, y, z */ 
dx, dy, dz */ 
View Reference Point to View Plane */ 
View Reference Point to Front Clip Plane */ 
View Reference Point to Back Clip Plane */ 
PARALLEL or PERSPECTIVE */ 

Meaning depends on projection type */ 
umin, Umax, vmin, vmax */ 
dx, dy, dz */ 
xmin, xmax, ymin, ymax, zmin, zmax */ 


The view^parametera argument is a pointer to a structure as defined above. 
set_viewing_parameters fills in the associated structure with the current values of the 
viewing parameters. The parameters are: 

vwrefpt An array of three floats describing the coordinates of the view reference point. 

vwplnorm An array of three floats describing the direction of the view plane normal vector. 

viewdis A float describing the distance of the view plane from the view reference point. 
frontdis A float describing the front clipping distance. 

backdis A float describing the back clipping distance. 

projtype A int describing the projection type. 

pfojdir An array of three floats describing the direction of projection. The meaning of 
prof dir is dependent on the projection type: 

PARALLEL projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 

windou) An array of four floats describing the boundaries of the viewing window. 
vwupdir An array of three floats describing the view up direction. 
viewport An array of six floats describing the boundaries of the viewport. 


3.4. Viewing Control 


S.4‘1. set_window_clipping — Enable Clipping in the View Plane 

set_window_clipping enables or disables clipping against the window in the view plane. 

set_window_clipping(on_off) 

int on_off; /* true = turn clipping on */ 

/* FALSE = turn clipping off */ 
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The on-off argument specifies whether window clipping is enabled or not. A value of FALSE rfw- 
ahle 9 window clipping, whereas a value of TRUE enables window clipping. 

When window clipping is off, objects described to SunCore are not checked to insure that they 
lie within the window when projected onto the view plane. When window clipping is on, objects 
described to SunCore are clipped to the window. 

SunCore initializes window clipping to TRUE. 

Note that window clipping is done before segment primitives are written to the pseudo display 
file. This means that subsequent image transformations may extend images beyond the bounds 
of the viewport. SunCore has optional output clipping (an extension to the ACM Core 
specification) to correct for this. See the se't_out:put_clipping function described below. 


set_front_plane_clipping —Enable Depth Clipping 

set_front_plane_clipping enables or disables clipping against the front clipping plane. 


se t_ f r o nt:_p 1 ane_c 1 ipp ing (f r on t_o n_o f f) 
int front_on_off; 

The front_on_off argument specifies clipping enabled or disabled for the front clipping plane. A 
value of FALSE means disable the clipping, and a value of TRUE enables the clipping. Clipping is 
disabled by default. 


S.4-3, set_back_plane_clipping — Enable Depth Clipping 

set:_back_plano_clipping enables or disables clipping against the back clipping plane. 


set_back_plane_clipping(back_on_of f) 
int back„on_off; 

The back_on_off argument specifies clipping enabled or disabled for the back clipping plane. A 
value of FALSE means disable the clipping, and a value of TRUE enables the clipping. Clipping is 
disabled by default. 


3.4-4- set_output_clipping (SunCore extension) 

SunCore supports output clipping, which is done after image transformations on segments, as 
an option in addition to window clipping. The set_output_clipping function enables or 
disables output clipping. 

sot_output_cl ipping (on_o f f ) 

int on_off; /* TRUE = turn on clipping */ 

/* FALSE = turn off clipping */ 

If output clipping is enabled, it places a clipping process after the image transformation specified 
by the dynamic segment attribute. This ensures that everything is correctly clipped to the 
viewport. 
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set_coordinate_system_t:ype 

set:_coordina-te_system_t:ype selects a left-handed or right-handed world coordinate sys¬ 
tem. 

set_coordlnato_systein_type (type) 

int typo; /* right = right handed coordinates */ 

/* LEFT = left handed coordinates */ 


$4.6. set_world_coordinate„matrix_2 — Specify World or Modelling Transform 

set_world_coordinate_matrix_2 specifies a 3X3 matrix containing the ‘world 
transform’ or modelling transform. This matrix is concatenated with the ‘viewing transform’ to 
give the ‘composite viewing transform’. The composite viewing transform is the transform that 
is actually used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. Currently, this function does not modify column 2 of the matrix. 
This function may be called at any time, even in the midst of putting output primitives into a 
segment. 

set_world_coordinate_matrlx_2 (array) 

float array[3][3]; /* [row] [column] */ 

Note that the matrix order is such that: 

znew=x*arrayQQ+y*arrayiQ-i‘array2jfy 


ynew—z*arrayQij-y*array I i+array 2^1 


S. 4 . 7 . set_world_coordinate_inatrix_3 — Specify World or Modelling Transform 

set„world_coordinate_matrix_3 specifies a 4X4 matrix containing the ‘world 
transform’ or modelling transform. This matrix is concatenated with the ‘viewing transform to 
give the ‘composite viewing transform’. The composite viewing transform is the transform that 
is actually used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. Currently, this function does not modify column 3 of the matrix. 
This function may be called at any time, even in the midst of putting output primitives into a 
segment. 

set_world_coordinate_matrix_3 (array) 

float array[4] [4]; /* [row] [column] */ 

Note that the matrix order is such that: 

xnew=x*arrayQQ+y*arrayiQ+z*array2fl+array^Q 


ynew=x*arrayQyi-y*arrayi^^+z*array2^i+array^j^ 
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znew—x*arrayQ^-^y*array-^^-^-z*array2^'\-(^Tray^^ 


3.4.8. map_ndc_to_world_2 — Convert NDC to World Coordinates 

map_ndc_to_wor ld_2 maps a point in normalized device coordinate (NDC) space to its world 
coordinates. 

inap_ndc_to_world_2(ndcx, ndcy, wldx, wldy) 
float ndcx^ ndcy; 
float *wldx, *wldy; 


3.4 9 . map_ndc_to_world _3 — Convert NDC to World Coordinates 

inap_ndc_to_world_3 maps a point in normalized device coordinate (NDC) space to its world 
coordinates. 

map_ndc_to_world_3(ndcx, ndcy, ndcz, wldx, wldy, wldz) 
float ndcx, ndcy, ndcz; 
float *wldx, *wldy, *wldz; 


3.4^10. map_world_to_ndc _2 — Convert World to NDC Coordinates 

inap_world_to_ndc_2 maps a point in world coordinates to its normalized device coordinates 
(NDC). 


inap_wor1d_to_ndc_2(wldx, wldy, ndcx, ndcy) 
float wldx, wldy; 
float *ndcx, *ndcy; 


3 . 4 -li- niap_world_to_ndc _3 — Convert World to NDC Coordinates 

map_wor ld_to_ndc_3 maps a point in world coordinates to its normalized device coordinates 
(NDC). 


xnap_world_to_ndc_3(wldx, wldy, wldz, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz; 
float *ndcx, *ndcy, *ndcz; 


3.5. Inquiring Viewing Characteristics 

SunCore provides a number of functions for inquiring about parameters of the viewing operas 
tions. There are a number of separate calls available for inquiring about individual parameters, 
then there is a composite inquire_viewing_parameters function which obtains all the 
viewing parameters in one fell swoop. The individual calls provided are summarized here and 
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described in detail in the subsections following. 

Table 3-6: Summary of Functions for Inquiring Viewing Parameters 


Fvnction 

Deecripiion 

inquire_view_re ference_point 

Obtains the view reference point in world coordinates. 

inquire_view_p1ane_norma1 

Obtains a vector which determines the view plane, rela^ 
tive to the view reference point. 

inquire_view_plane_distanco 

Obtains the distance from the view reference point to 
the view plane. 

inquire_view_depth 

Obtains the distance from the view reference point to 
the ‘front’ clipping plane (also known as the ‘hither’ or 
‘near’ clipping plane), and the distance from the view 
reference point to the ‘back’ clipping plane (also known 
as the ‘yon’ or ‘far’ clipping plane). 

inc[uire_proj action 

Determines which projection type is in use, and returns 
either the center of projection (for PERSPECTIVE projec¬ 
tion) or direction of projection (for PARALLEL projec¬ 
tion). 

inquire_view_up_2 

Determines the view up direction in two dimensions. 

inquire_view_up_3 

Determines the view up direction in three dimensions. 

inquire_viewport_2 

Obtains the coordinates of the two-dimensional 
viewport. 

inquire_viewport_3 

Obtains the coordinates of the three-dimensional 
viewport. 

inquire_vindow 

Obtain the boundaries of the viewing window. 

inquire_viewing_paraiiieters 

is a composite function which does all of the above 
functions at one time. 

inquire_ndc_space_2 

Determine the size of the normalized device coordinate 
space in two dimensions. 

inquire_ndc_space_3 

Determine the size of the normalized device coordinate 
space in three dimensions. 


3.5.1. inquire_view_reference_point 

inquire_view_reference_point obtains the coordinates of the view reference point. 

inquire_view_reference_point(x, y, z) 

float *x, *y, * 2 ; /* X, y, and z Coordinates */ 

3.5.2. inquire_view_plane_norinal 

inquire_view_plane_normal obtains the coordinates of the view plane normal vector. 
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inquire_view_plane_norinal (dx, dy, dz) 

float *dx, *dy^ *dz; /* x, y, and z deltas */ 


S.5.3. inquire_view_plane_distance 

inquire_view_plane_distance obtains the distance of the view plane from the view refer¬ 
ence point. 

inquire_view_plane_distanco(view_distance) 
float *view_distanco; 


S.S.4> inquire_view_depth 

inquire_view_depth obtains the distances of the front and back clipping planes from the 
view reference point. 

inquire__view_depth(front_distance, back^distance) 
float * front_distance, *back_distance; 


S.5.5. inquire_prejection 

inquire^prejection obtains the current projection type and the coordinates of the center of 
projection (for PERSPECTIVE projections) or the direction of projection (for PARALLEL projec¬ 
tions). 


inquire_projection(projection^typo, dx, dy, dz) 
int *projection_type; 

float *dx, *dy, *dz; /* x, y, and z deltas */ 


3.5.6. inquire_view_up_2 

inquire_view_up_2 obtains the view up direction in two dimensions. 

inquire_,view_up_2 (dx, dy) 

float *dx, *dy; /* x and y directions */ 


3.5.7. inquire_view_up_3 

inqpiire_view_up_3 obtains the view up direction in three dimensions. 

inquire_view_up_3(dx, dy, dz) 

float *dx, *dy, *dz; /* x, y, and z directions */ 
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S.5.8. inquire_ndc_space_2 

inquire_ndc_spaco_2 obtains the dimensions of the Normalized Device Coordinate space in 
two dimensions. 

inquire_ndc_space_2 (width, height) 
float ‘width, ‘height; 



$.5.9. inquire_ndc_space_3 

inquire_ndc_space_3 obtains the dimensions of the Normalized Device Coordinate space in 
three dimensions. 

inquire_ndc_space_3(width, height, depth) 
float ‘width, ‘height, ‘depth; 


3.5.10. inquire_viewport_2 

inquire_viewport_2 obtains the coordinates of the two-dimensional viewport. 

inquire_viewport_2 (xmin, xmax, ymin, ymax) 
float ‘xmin, ‘xmax; 
float ‘ymin, ‘ymax; 



3.5.11. inquire_viewport_3 

inquire_viewport_3 obtains the coordinates of the three-dimensional viewport. 

inquire_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float ‘xmin, ‘xmax; 
float ‘ymin, ‘ymax; 
float ‘zmin, ‘zmax; 


3.5.12. inquire_window 

inquire_window obtains the boundaries of the viewing window. 

inquire_window (umin, umax, vmin, vmax) 
float ‘umin, ‘umax; 
float ‘vmin, ‘vmax; 


o 
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3.5,1S. inquire_viewing_parameters 


inquire_viewing_paramoters returns a collection of information pertaining to the current 
parameters of the viewing system. 

inquiro_viewing_parameters(view_parameters) 
struct ■{ 

float vwrefpt[3]; /* x, y, z */ 
float vwplnorm[3]; /* dx, dy, dz */ 

float viewdis; /* View Reference Point to View Plane */ 

float frontdis; /* View Reference Point to Front Clip Plane */ 
float backdis; /* View Reference Point to Back Clip Plane */ 

int projtype; /* PARALLEL or perspective */ 

float projdir [3]; /* Meaning depends on projection type */ 

float window[4]; /* umin, umax, vmin, vmax */ 
float vwupdir[3]; /* dx, dy, dz */ 

float viewport[6]; /* xmin, xmax, ymin, ymax, zmin, zmax */ 

} *view_parameters; 


The view_parameter8 argument is a pointer to a structure as defined above. 
inquire_viewing_parameters fills in the associated structure with the current values of 
the viewing parameters. The parameters are: 

vwrefpt An array of three floats describing the coordinates of the view reference point. 

vwplnorm An array of three floats describing the direction of the view plane normal vector. 

viewdis A float describing the distance of the view plane from the view reference point. 
frontdis A float describing the front clipping distance. 

backdis A float describing the back clipping distance. 

projtype A int describing the projection type. 

projdir An array of three floats describing the direction of projection. The meaning of 
projdir is dependent on the projection type: 


PARALLEL 

projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 

window An array of four floats describing the boundaries of the viewing window. 
vwupdir An array of three floats describing the view up direction, 
viewport An array of six floats describing the boundaries of the viewport. 


$.5.14- inquire_wor ld_coordinate_matrix_2 

inquire_world_coordinate_matrix_2 returns a 3 by 3 matrix containing the ‘world 
transform’ or modelling transform. This matrix is concatenated with the ‘viewing transform’ to 
give the ‘composite viewing transform’. The composite viewing transform is the transforjn that 
is actually used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. 
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inquire_world_coordinatojuatrix_2 (array) 

float array[3][3]; /* array[row][col] */ 



3.5.15. inquire_world_coordinate__matrix_3 

inquire_world_coordinate_matrix_3 returns a 4 by 4 matrix containing the ‘world 
transform’ or modelling transform. This matrix is concatenated with the ‘viewing transform’ to 
give the ‘composite viewing transform’. The composite viewing transform is the transform that 
is actually used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. 

inquire_world_coordinate_matrix_3(array) 

float array[4][4]; /* array[row][col] */ 


3.5.16. inquire_inverse_composite_matrix (SunCore Extension) 

SunCore uses the matrix inverse of the composite viewing transform internally for operations 
such as map^ndc^to^world. This matrix may at times be useful to the applications program. 

lnquire_lnverse_conqposite_matrix(array) 

float array[4][4]; /* array[row][col] */ 


3.5.17. inquire_viewing_control_parameters 


inquire_viewing_control_parameters obtains the enabled status of clipping, and the 
type of world coordinates in use. 


inquire_viewing_control_parameters (windowclip, frontclip, backclip, type) 


int *windowclip; 
int *frontclip; 
int ^backclip; 
int *typo; /* 


/* TRUE if window clipping enabled */ 

/* TRUE if front plane clipping enabled */ 
/* TRUE if back plane clipping enabled */ 
RIGHT or LEFT world coordinate system type */ 
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All output primitives for a graphical object are placed in a segment by SunCore on request 
from the application program. Each segment defines an image which is a view of the object and 
which is part of the picture displayed on the view surface. An application program describes an 
object by creating a segment, calling output primitive functions (the results of which are placed 
in the segment), and then closing the segment. 

There are two kinds of segments, namely: temporary segments and retained segments. Retained 
segments have an image_transformation_t:ype which specifies how they can be 
transformed. Retained segments can be made visible or invisible, detectable (via the pick input 
function) or undetectable, highlighted, and may be transformed, depending on their type. 

Retained segments have names (actually numeric identifiers) so that by placing output primitives 
in such segments, the application programmer can selectively modify parts of the picture by 
deleting and recreating segments (which effectively replaces them) so that their images change. 
Retained segments are stored in the display list for later dynamic modification. 

Temporary segments are not saved in the display list, are only drawn once, and may not be 
modified dynamically. A new_frame action deletes all portions of any temporary segments 
which have already been drawn. 


4.1. Retained Segment Attributes 

In the same way that primitive attributes affect the output primitives, retained segment dynamic 
attributes affect the characteristics of retained segments. From now on, the term dynamic attri¬ 
butes means the dynamic attributes of retained segments. 

As well as being identified by the name of the retained segment into which they have been 
placed, output primitives may also be assigned a primitive attribute known as a pick identifier or 
pick-id. This means that within the single level of segmentation, another level of naming is pro¬ 
vided. An example of the use of pick-id might be that all the character strings for (say) a menu 
could appear in a single segment, where each character string is assigned a different pick-id. 
Then when the user is using the mouse to select a specific item from the menu, the application 
program uses the PICK input function to find out which menu item was selected. 

Retained segments have one static attribute and four dynamic attributes. Attributes, and the 
means of setting them and enquiring their values, are described in detail in chapter 6. 

The only static attribute of retained segments is the iinage_transforinat:ion_t:ypo. This 
attribute can have one of five values: 
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None 

The segment is a retained segment on which no transformations may be applied. 

Tramlatable 2-D 

The segment is a retained segment which may be translated in two dimensions. 

Transformable 2-D 

The segment is a retained segment which may be fully translated, scaled, and rotated, in two 
dimensions. 

Translatable S-D 

The segment is a retained segment which may be translated in two or three dimensions. 
Transformable S-D 

The segment is a retained segment which may be fully translated, scaled, and rotated, in two 
or three dimensions. 

SunCore sets image_transforma'tion_'type to the default value of NONE at initialization 
time. 

The four dynamic attributes of retained segments are defined here. 

Visibility indicates whether the segment should have a visible image. There are only two 

values of this attribute, namely; TRUE and FALSE. 

SunCore sets the default value of visibility to TRUE at initialization time. 

Highlighting indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by blinking. There are only two values of the highlighting 
attribute, namely: TRUE and FALSE. When highlighting is turned on, the seg¬ 
ment is blinked once. 

SunCore sets the default value of highlighting to FALSE at initialization time. 

Detectability indicates whether the retained segment can be detected by the pick device 
(mouse pointing device). See the await_pick function. The values for the 
detectability attribute, are: 0 through 2,147,483,647. SunCore sets the default 
value of detectability to 0 at initialization time. 

Image^transformation 

indicates how the image of a retained segment, in normalized device coordi¬ 
nates, is scaled, rotated, or translated. A segment’s static 
image^transformation^type attribute limits the values which its 
image^transformation attribute may have. See the set of functions called 
set_segment:_iinage_a;a:a: in chapter 6. 

SunCore sets the default value of image„trans formation to the identity 
transformation at initialization time. 

4.2. Retained Segment Operations 
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4.2.1. create_retained_seginent ~ Create a New Segment 

creat:e_r©tained_segiDent: creates a new, empty, open segment. 

create_retained_segiiient (segment_namo) 

int segm©nt_naino; /* Segment Identifier */ 

The segment_name argument defines a segment number in the range 1 through 2,147,483,647. 

The image transformation type for the newly created segment is obtained from the current attri¬ 
bute value for image_transformation_type. The dynamic attribute values for the newly 
created segment are obtained from the default values of the dynamic attributes for retained seg¬ 
ments. 

Use the set:_image_t:ransforma1:ion_type function, before calling 
create_ret:ained_segment, to specify whether the created segment is translatable or 
transformable. After calling creat:e_retained_segiaent:, the specified segment is said to be 
“open”. This means that output primitives can now be called upon to add graphics primitives 
(lines, text, polygons, and so on) to this segment. 

Only one segment can be open at a time. 

Errors returned from create_retained_segment:: 

• The set of currently selected view surfaces is empty. 

• The current viewing specification is inconsistent. 

• There is already an open segment. 

• A retained segment named segment_name already exists. 

• The default value of imag©_t:rans format ion is invalid for the current 
image_trans formation_type. 


4 . 2 . 2 . close_retained_seginent — Close a Segment 

close_retained_segment closes the currently open segment. Dynamic segment attributes 
may be changed both before and after closing the segment. 

close_retained_segment () 

Errors returned from close_segment: 

• There is no open retained segment. 


4 . 2 . 3 . delete_retained_segmen't — Delete a Retained Segment 

delete_retained_segment deletes a specifically named segment. 

delet©_retain©d_segment (s©gment_name) 

int segm©nt_name; /* Segment Identifier */ 
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The segment specified by the segmen't_name argument is deleted, 
deleted is the currently open segment, it is closed before it is deleted, 
erased from all view surfaces. 


If the segment being 
The deleted segment is 


Errors returned from dele‘te_ret:ained_segment:: 

• There is no retained segment with the name seginent:_r^ame. 


1^,2. rename_retained_seginent —Rename a Retained Segment 

rename_retained_segment changes the name of a retained segment. 

renaine_r©tained_segmGnt(segment^namo, newnamo) 

int segment_name; /* Old Segment Identifier */ 

int newname; /* New Segment Identifier */ 

The segment whose identity is segment_name is renamed as newname, and this name must be 
used in any future references to that segment. The segment segment_name is no longer acces¬ 
sible. 

Errors from rename_retained_segment: 

• There is no retained segment with the name segment:_name. 

• Tliere is an existing retained segment named new_name. 


^.2.5. delete_all_retained_seginents 
delete_all_retained_segments deletes all retained segments. 

delet©_all_retained_segments() 

All retained segments are deleted. If there is a currently open retained segment, it is closed 
before it is deleted. 



2.6. inquire_retained_segment_sur faces 

incjuire_retained_segment_sur faces obtains the number and names of the view sur¬ 
faces upon which this segment gets drawn. These view surfaces were ‘selected’ when the seg¬ 
ment was created. 


inquir©_retained_segment_sur faces(segment_namo, array^size, 

view_sur face_array, number_o f_sur faces) 
int segment_name; /* Name of Segment */ 

int array_size; /* Size of View Surface Array */ 

struct vwsurf view_surface_array[]; /* Array of view surface names */ 

int *numbor_of_sur faces; /* Returned number of surfaces */ 


The number of view surfaces selected at the time the retained segment name given by 
segment_namo was created is copied into number_of_sur faces. The names of those sur¬ 
faces are copied into view_surface_array, where the array is an array of view surface 



4-4 


Revision F of 15 May 1985 






SunCore Reference Manual 


Segmentation and Naming 


names. array_size is specified by the caller, and is the size of view_surface_array. 
The view surface structure is defined in the usercore.h header file. 

If nuinber_of_sur faces is greater than array_8izt, only array_sizo view surface names 
are copied into vtew_8urface^array. If array_sizo is less than or equal to zero, no names are 
returned. 

Errors from inc[uire_retained_,segmen‘t_surfaces: 

• There is no retained segment with the name seginent_naiiie. 


4 . 2 .7. inquire_retained_secfTnent_names 

inquire_retained_seginent:_names obtains a list of the retained segments names. 

inquire_retained_segment_names (array_size, nama_array, nuinber_of_segments) 


int 

array_size; 

/* 

Size of Array */ 

int 

name_array[]; 

/* 

Segment 

Identifiers */ 

int 

* number_o f_segments; 

/* 

Number 

of Segments */ 


The namo_array argument is an array which is to receive a list of the existing retained seg¬ 
ments. array_size specifies the number of elements in name_array. The 
numbet^of^zegments argument is returned to the caller, and is the number of existing retained 
segments. If the number of existing retained segments is greater than the size of the array, only 
array_size segment names are copied into the array. If array_size is less than or equal to 
zero, no segment identifiers are returned. 


4 . 2 . 8 . inquire_open_retained_segment 

inquire_open_re'tained_segment obtains the name of the currently open retained seg¬ 
ment. 


inquire_open_retained_segnient (segment_nzune) 

int *segment_name; /* Segment Name */ 

The name of the currently open retained segment (if there is one) is copied into the 
segfment_name variable. If there is no currently open retained segment, segment_name is 
set to zero. 


4.3. Temporary or Non-Retained Segments 

Temporary segments are used for transient images. Temporary segments cannot be modified 
dynamically, and all portions of temporary segments which have already been drawn are deleted 
upon any new frame action. Primitives placed in temporary segments are not stored in the 
display list. 
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^.3.1. create_temporary_segment 

crea-te_t:emporary_segment creates a new, empty, nonretained or temporary, segment. 
Greate_ten5Jor ary_segment () 


j^.3.2. close_temporary_segment 

close_teinporary_segmen't closes the currently open temporary segment. 
closo_teniporary_segment () 


^.3.3. inquire_open_temporary_seginent — Get Temporary Segment Status 

inquire_open_temporary_seginent determines whether there is a currently open tem¬ 
porary segment. 

inquire_open_tenporary_segment (open) 

int *open; /* Receives status of ten^orary segment */ 

The open argument receives the status of whether there is a currently open temporary segment: 
FALSE There is no currently open temporary segment. 

TRUE There is a currently open temporary segment. 


4.4. Saving and Restoring Segments on Disk (SunCore Extension) 

The two functions described in this section provide for saving segments on disk files and restor¬ 
ing segments from disk files. Only one segment is saved in a given file. 


4 . 4 . 1 . save_segmerit — Save Segment on Disk File (SunCore Extension) 

savo^segment saves the named retained segment on a specified disk file. 

save.segment (segment^name, filename) 

int segment_name; /* Name of segment to save */ 

char * filename; /* Pointer to a UNIX filename */ 

Saved primitives are in normalized device coordinates. Dynamic segment attributes are also 
saved. 
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restore_segment — Restore Segment from Disk File (SunCore Extension) 

rest:ore_segment restores the named retained segment from a specified disk file. A new seg¬ 
ment is created and the segment from the disk file is copied into it. The segment is then closed. 

restore_segment(segment_name, f1lename) 

int segment_name; /* Name of segment to create */ 

char * filename; /* Pointer to a UNIX filename */ 
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Chapter 5 


Output Primitives 


Output Primitives serve to describe objects in the world coordinate system. When the output 
primitive functions are called, primitives are placed in the currently open segment via drawing 
commands which eventually produce line and character output. 

SunCore supports six kinds of output primitives, namely moves, lines and polylines, polygons, 
text, markers and polymarkers, and rasters. The table below summarizes these types of func¬ 
tions: 


Table 5-1: Summary of Output Primitive Functions 


Primitive 


Description 


Move 

Line 

Polyline 

Polygon 

Text 

Marker 

Polymarker 

Rasters 


primitives alter the value of the Current Position (described below), 
primitives describe lines in world coordinates. 

primitives describe sequences of connected lines in world coordinates, 
primitives describe a closed polygon which will be filled with a color. The polygon 
primitives are a SunCore extension to the ACM Core specification, 
primitives describe character strings on the display. 

primitives describe markers which are written on the display in a constant orien¬ 
tation, independent of any transformations which may be in effect, 
primitives describe a sequence of markers which are written on the display in a 
constant orientation, independent of any transformations which may be in effect, 
primitive describes an array of one-bit or eight-bit pixels. 


All primitive operations use world coordinates. Some of these operations affect the value known 
as the Current Position. The Current Position defines the current drawing location in the world 
coordinate system. SunCore maintains the value of the Current Position at all times. At ini¬ 
tialization time, the Current Position is initialized to the origin of the world coordinate system. 

In both two dimensions and three dimensions, coordinate positions can be specified in terms of 
absolute world coordinates, or coordinates can be specified relative to the Current Position. 

A segment must be open (see the creato_*a:j*x_segment functions) before any output primi¬ 
tives may be used. A segment contains a set of output primitives which can subsequently be 
manipulated as a unit. 

An output primitive is processed as follows: 
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1. Tne primitive is transformed to clipping coordinates using the composite viewing transform. 
This places the window boundaries at «mm=—32767, «moz=+32767, umin =—32767, and 
vmoz =+32767. The front clipping plane is at z=0 and the back clipping plane is at 
z=+32767. 

2. The primitive is then clipped to the boundaries just mentioned if window clipping is enabled. 

3. The output primitive is then output scaled to the viewport which is specified in normalized 
device coordinate space. 

4. The resulting primitive is then copied to the display list or pseudo display file (PDF) if the 
open segment is a retained segment. 

5. Next, the primitive is transformed using the image transform which is an attribute of 
retained translatable or retained transformable segments, 

6. The output primitive is then clipped again to the viewport boundaries if output clipping is 
enabled. 

7. For each view surface which was selected when the segment was created, the primitive is 
then converted to physical device coordinates and drawn on the view surface. 

If a change is made to certain dynamic segment attributes of a retained segment, the primitives 

in that segment are recovered from the PDF and used to erase the segment (if necessary) and 

redraw the segment following steps 5 through 7 above. The diagram below shows the above pro¬ 
cess in a graphical form. 
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Figure 5-1: Flow Diagram of Output Primitive Processing 
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Output primitives are drawn with the static primitive attributes set by the primitive attribute 
functions (see chapter 6). 


5.1. Moving the Current Position 

There are four functions for moving the Current Position. move_abs_2 and move_abs_3 
change the Current Position to an absolute position in world coordinates, whereas move_rol_2 
and move_rel_3 change the Current Position by a delta relative to the Current Position. 

Note that move_abs_2 and move_rel_2 are simply short forms of the corresponding three- 
dimensional functions. The z coordinate of move_abs_2 is the z coordinate of the Current 
Position. The z delta of move_rel_2 is taken as zero. 


5,1.L move_abs_2 —Move to Absolute 2D Position 
move_abs_2 moves the Current Position to an absolute position. 
move_abs_2(x, y) 

float X, y; /* x and y coordinates to move to */ 

The Current Position is set to the values of 2 and y in two-dimensional world coordinates. 
inove_abs_2 only sets the Current Position; no drawing commands are output. 

5.1.2. Tnove_abs_3 — Move to Absolute 3D Position 
move_abs_3 moves the Current Position to an absolute position. 
move_abs_3(x, y, z) 

float x, y# z; /* x, y, and z coordinates to move to */ 

The Current Position is set to the values of x, y, and z in three-dimensional world coordinates. 
move_abs_3 only sets the Current Position; no drawing commands are output. 


5.1.3. inove_rel_2 — Move to Relative 2D Position 
iDove_rel_2 increments the Current Position by the values given. 
move_rel_2(dx, dy) 

float dx, dy; /* x and y coordinate deltas */ 

The Current Position is set to the value of Current Position plus dx and dy in two-dimensional 
world coordinates. move_rel_2 only sets the Current Position; no drawing commands are 
output. 
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5.1.^. inove_rel_3 — Move to Relative 3D Position 
move_rel_3 increments the Current Position by the values given. 
iiiove_rel_3 (dx, dy, dz) 

float dx, dy, dz; /* x, y, and z coordinata deltas */ 

The Current Position is set to the value of Current Position plus dz, dy, and dz in three- 
dimensional world coordinates. move„rel_3 only sets the Current Position; no drawing com¬ 
mands are output. 


5.2. Position Enquiry Functions 

The position enquiry functions return the coordinates of the Current Position to the caller. 


5.2.1, inquire_current_position_2 —Enquire 2D Position 

inquire_current_posit:ion_2 returns the two-dimensional world coordinates of the 
Current Position to the caller. 

inquire_current_positioi._2 (x, y) 
float *x, *y; 


5.2.2. inquire_current_position_3 —Enquire 3D Position 

incjuire_current_position_3 returns the three-dimensional world coordinates of the 
Current Position to the caller. 

inquire_current_position_3(x, y, z) 
float *x, *y, *z; 


5.3. Line Routines 

The line routines draw lines on the currently selected SunCore view surfaces. Attributes of the 
line can be specified with additional calls to primitive attribute setting routines. 

The primitive attributes of line index, linestyle, linewidth, and pick^id are applicable for lines. 

Error Codes from the Line Functions: 

• There is no open segment. 

5.3.1. line_abs_2 — Describe Line in Absolute ^ Coordinates 
line_abs_2 describes a line in two-dimensional world cocrdinates. 


Revision F of 15 May 1985 


5-5 






Output Primitives 


SunCore Reference Manual 


line_abs_2(x, y) 
float X, y; 

The line that lino_abs_2 describes extends from the Current Position to the position specified 
by the x and y coordinates. 

The Current Position is updated to the coordinates specified by z and y. 

5.3.2. line_abs_3 — Describe Line in Absolute 3D Coordinates 

line_abs_3 describes a line in three-dimensional world coordinates. 

line_abs_3(x, y, z) 
float X, y, z; 

The line that line_abs_3 describes extends from the Current Position to the position specified 
by the z, y, and z coordinates. 

The Current Position is updated to the coordinates specified by z, y, and z. 


5.3.3. line_rel_2 — Describe Line in Relative 2D Coordinates 
line_rel_2 describes a line in two-dimensional world coordinates. 

line_rel_2(dx, dy) 
float dx, dy; 

The line that line_rel_2 describes extends from the Current Position to the position specified 
by the Current Position plus the dx and dy coordinates. 

The Current Position is updated by the deltas specified by dx and dy. 


5 . 3 . 4 ^ line_rel_3 — Describe Line in Relative 3D Coordinates 

line_rel_3 describes a line in three-dimensional world coordinates. 

line_rel_3(dx, dy, dz) 
float dx, dy, dz; 

The line that line_rel_3 describes extends from the Current Position to the position specified 
by the Current Position plus the dx, dy, and dz coordinates. 

The Current Position is updated by the deltas specified by dz, dy, and dz. 


5.4. Polyline Routines 

The polyline functions describe connected sequences of lines. The first two or three arguments 
to a polyline function are arrays of the appropriate coordinates. Consider the polyline function: 
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polyline_abs_3(x^array, y_array, z_array, n) 

float x_array[], y_array[], z_array[]; /* x, y, and z arrays */ 
int n; /* Number of coordinates */ 

The sequence of lines that these arrays of coordinates describe starts at the current position, 
then draws to: (j_flrray[0], y_array[0], 2 _arfay[ 0 ]), then runs through the intermediate array 
values and ends at (z_flrraj/(n—1], jA_arr(iy[rt-“lj, z_array[n—1]), where n is the number of ele¬ 
ments in each of the coordinate arrays. There are thus n lines in the figure described. 

Error Codes from the Polyline Functions: 

• The number of coordinates, n, is less than or equal to zero. 

• There is no open segment. 


5 , 4 . 1 . polyline_abs_2 —Describe Line Sequence in Absolute 2D Coordinates 

polyline_abs_2 describes a line sequence in absolute two-dimensional world coordinates. 

polyline_abs_2(x_array. y_array, n) 

float x_array[], y_array[]; /* x and y coordinates */ 

int n; /* number of array elements */ 

The Current Position is updated to the end of the last line drawn. 


5 . 4 . 2 . polyline_abs_3 — Describe Line Sequence in Absolute SD Coordinates 

polyline_abs_3 describes a line sequence in absolute three-dimensional world coordinates. 

polyline_abs_3(x_array, y_array, z_array, n) 

float x_array[], y_array[], z_array[]; /* x, y, and z arrays */ 
int n; /* number of elements */ 

The Current Position is updated to the end of the last line drawn. 


5 . 4 . 3 . polyline_rel_2 — Describe Line Sequence in Relative 2D Coordinates 

polyline_rel_2 describes a line sequence in relative two-dimensional world coordinates. 

polyline_rel_2(dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y delta arrays */ 
int n; /* number of array elements */ 

The sequence of lines that this function describe starts at the current position, moves to: current 
position -f (dz_array[0], rfy_array[Ol) then draws to: current position -h {dx_array[0\, 
dy_array\0]) -H (rfz_array[l], rfy_flfray[l]) and so on. The Current Position is updated to the end 
of the last line drawn. 
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polyline_rel_3 — Describe Line Sequence in Relative 3D Coordinates 
polyline_rel_3 describes a line sequence in relative three-dimensional world coordinates. 



po ly 1 ine_rel_3 (dx_array, dy_array^ d 2 _array, n) 

float dx_array[], dy_array[], dz_array[]; /* x, y, and z delta arrays */ 
int n; /* number of elements */ 


The sequence of lines that this function describe starts at the current position, moves to: current 
position -I- (dx_array[Q\, dy_array[Q], dz_arraylO]) then draws to: current position + 
{dz_array[0], rfj/:_«rfay[0], dz_arTay^\) 

(rfz_orray[l], [l], rf^_array[l]) and so on. The Current Position is 

updated to the end of the last line drawn. 


5.5* Text Routines 


5.5.1. text — Draw Character String In World Coordinates 

text draws a character string in world coordinates. 

text(string) ; 

char ‘string; 

The character string specified by string is drawn from the Current Position. The Current Posi¬ 
tion is unchanged. The font, size, orientation, and so on, are set by calls to the set primitive 
attribute functions. 

Error Codes from the Text Function: 

• There is no open segment. 

• The character string contains one or more characters which cannot be drawn. 

• The vectors that the current ckarpath and champ attributes describe are parallel. 



5.6. Text Enquiry Functions 

Text enquiry functions obtain the length that a character string would extend, in world coordi¬ 
nates, if the character string were actually drawn according to the current text primitive attri¬ 
butes. 

Error Codes from the Text Enquiry Functions: 

• inquire_text:_ext:ent„2 was used to obtain the Current Position when 
inquire_text_extent_3 should have been used in order to avoid loss of information. 

• The character string contains one or more characters which cannot be drawn. 

• The vectors that the current ckarpath and champ attributes describe are parallel. 

o 
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5 , 6 . 1 . iriquire_text_extent_2 

inquire_text_extent_2 obtains the two-dimensional extent, in world coordinates, of the 
specified character string. 

inquire_text_extent_2(string, dx, dy) 
char *string; 
float *dx, *dy; 

inquire_text_extent_2 returns the extent of the character string specified by ttring, if the 
character string were drawn, unjustified, from the Current Position. The extent is returned in 
dx and dy in world coordinates relative to the Current Position. 

The specified character string, and the values of the primitive attributes font, champ, char the, 
ckarpath, charspace, and ckarprecision are used to calculate the vector which represents the 
extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful values if char~ 
precision is CHARACTER. 


5 . 6 . 2 . inquire_text_extent_3 

incjuii"e_t©xt_ex‘t©nt_3 obtains the three-dimensional extent, in world coordinates, of the 
specified character string. 

inquir©_text_extent_3(string, dx, dy, dz) 
char ‘string; 
float *dx, *dy, ‘dz; 

inquire_text_extent_3 returns the extent of the character string specified by string, if the 
character string were drawn, unjustified, from the Current Position. The extent is returned in 
dx, dy, and dz in world coordinates relative to the Current Position. 

The specified character string, and the values of the primitive attributes font, champ, charsize, 
ckarpath, charspace, and charprecision are used to calculate the vector which represents the 
extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful values if char~ 
precision is CHARACTER. 

5.7. Marker Functions 

The marker functions place a character at a specific location on the display. The polymarker 
functions place a character at a sequence of locations on the display. 

The marker character is any printable ASCII character, and is the value of the iiiark©r_syinbol 
primitive attribute. The marker_sytnbol primitive attribute is set by the 
set:_marker_syTnbo 1 function described in chapter 6. 

The markers are placed on the display without any of the rotations, translations, or scaling 
which is applied to text strings. Markers use the default orientation attributes. 


Revision F of 15 May 1985 


5-9 




Output Primitives 


SunCore Reference Manual 


Error Codes from the Marker Functions: 
• There is no open segment. 


5.7.L marker_abs_2 — Plot Marker at Absolute 2D Coordinates 
marker_abs_2 plots a marker at specified absolute two-dimensional world coordinates. 
inarker_abs_2 (X, y) 

float X, y; /* Absolute x and y Coordinates */ 

marker_abs_2 plots the marker at the absolute two-dimensional coordinates specified by the x 
and y arguments. The Current Position is updated to be this point. 

5.7.2. inarker_abs_3 — Plot Marker at Absolute 8D Coordinates 
marker_abs_3 plots a marker at specified absolute three-dimensional world coordinates. 
marker_abs_3(x, y, z) 

float X, y, z; /* Absolute x, y, and z Coordinates */ 

marker_abs_3 plots the marker at the absolute three-dimensional coordinates specified by the 
z, y, and z arguments. The Current Position is updated to be this point, 

5.7.S. inarker_rel_2 — Plot Marker at Relative 2D Coordinates 
marker_rel_2 plots a marker at a specified relative two-dimensional position. 
marker_rel_2 (dx, dy) 

float dx, dy; /* x and y Coordinate Deltas */ 

marker_rel_2 plots the marker at the position relative to the Current Position, specified by 
the deltas dx and dy. The Current Position is updated to be this point. 

5.7.4- niarker_rel_3 — Plot Marker at Relative 3D Coordinates 
marker_rel_3 plots a marker at a specified relative three-dimensional position. 
marker_rel_3 (dx, dy, dz) 

float dx, dy, dz; /* x, y, and z Coordinate Deltas */ 

marker_rel_3 plots the marker at the position relative to the Current Position, specified by 
the deltas dx, dy, and dz. The Current Position is updated to be this point. 
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5.7.5, polymarker_abs_2 — Plot Marker Sequence at Absolute 2D Coordinates 

polyiiiarker_abs_2 plots a sequence of markers at specified absolute two-dimensional posi¬ 
tions. 


polymarker_abs_2(x_array, y_array, n) 

float x_array[], y_array[]; /* Absolute x and y */ 
int n; /* Number of Coordinates */ 

polymarker_abs_2 plots a sequence of markers at the absolute positions specified by the 
x^array and y^array arguments, n specifies the number of coordinates in the arrays. The 
Current Position is updated to be the last point. 


5.7.6. polymarker_abs_3 — Plot Marker Sequence at Absolute 3D Coordinates 

polymarker_abs_3 plots a sequence of markers at specified absolute three-dimensional posi¬ 
tions. 


polymarker_abs_3 (x_array, y_array, z_array, n) 

float x_array[], y_array[]. z_array[]; /* Absolute x, y, and z */ 
int n; /* Number of Coordinates */ 

polymarker_abs_3 plots a sequence of markers at the absolute positions specified by the 
a:_arrfly, y^array, and z_array arguments. The number of coordinates in the array is given by 
the n argument. The Current Position is updated to be the last point. 


5.7.7. polymarker_rel_2 — Plot Marker Sequence at Relative 2D Coordinates 

polymarker_rel_2 plots a sequence of markers at specified relative two-dimensional positions. 

polymarker_rel_2(dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y Deltas */ 

int n; /* Number of Coordinates */ 

polymarker_rel_2 plots a sequence of markers at the positions relative to the Current Posi¬ 
tion, specified by the deltas dx_array and dy_array. The number of deltas in the arrays is 
specified by n. The Current Position is updated to be the last point. 

5.7.8. polymarker_rel_3 — Plot Marker Sequence at Relative 3D Coordinates 

polymarker_rel_3 plots a sequence of markers at specified relative three-dimensional posi¬ 
tions. 


polymarker_rel_3 (dx_array, dy_array, dz_array, n) 

float dx_array[], dy_array[], dz_array[]; /* x, y, and z Deltas */ 
int n; /* Number of Coordinates */ 

polymarker_rel_3 plots a sequence of markers at the positions relative to the Current Posi¬ 
tion, specified by the deltas dx_arrayj dy^array, and dz^array. The number of deltas in the 
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arrays is specified by n. The Current Position is updated to be the last point. 


5.8. Three-Dimensional Polygon Shading Parameters (SunCore 
Extension) 

When drawing three-dimensional polygons on the Sun color displays, several shading options are 
available. The routines described in this section provide shading control. These shading param¬ 
eters may be changed at any time and are not stored in the display list. Therefore a segment 
may be drawn with fast shading at one time, and then drawn again later with smooth shading. 


5.8.1. set_shading_parameters 

set_shad.ing_parameters specifies the parameters for rendering three-dimensional polygons 
on the color display. 

set_shading_parameters (ambient, diffuse, specular, flood, bump, hue, style) 
float ambient; /* percent background light */ 

float diffuse; /* percent diffuse reflection */ 

float specular; /* percent specular reflection */ 

float flood; /* percent flood lighting */ 

float burp; /* specular power 2 .. 9 */ 

int hue; /* color index range to generate */ 

/* 0=1.. 255, 1 = 1 .. 63 */ 

/* 2 = 64 .. 127, 3 = 128 .. 191 */ 

/* 4 = 192 .. 255 */ 

int style; /* Type of surface shading to do */ 

/* CONSTANT, GOURAUD, PHONG */ 

See set_polygon_interior_style for the ways in which these shading parameters are 
used. CONSTANT style shading gives constant intensity over the polygon using the color set by 
set_fill_index. GOURAUD style shading linearly interpolates between vertices (use only con¬ 
vex polygons) where the intensity at each vertex is set by the set_vertex_indices function. 
PHONG style shading produces smooth shading using the other parameters (only with convex 
polygons). 

The shading equation with PHONG is: 

pixelshade=ambient+diffu8e{L»N)-^-specular{H*NY'^”^^~{flood*2) 

where L is the direction vector of the light source, N is the surface normal vector, H is a vector 
which is the average of L and E (the eye direction vector), and z is depth in NDC. 

Here are some useful sets of PHONG parameters; 
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Table 5-2: Useful PHONG Parameters 


ambient 

0.05 

0.05 

diffuse 

0.94 

0.74 

specular 

0.0 

0.20 

flood 

0.0 

0.0 

bump 

0.0 

7.0 

hue 

0 

0 

style 

PHONG 

PHONG 


5.8.2. set_light_direction — Specify Direction of Light Source 

set_light_direction specifies the direction of the light source from the object. 

set_light_direction(dx, dy, dz) 
float dx, dy, dz; 

This assumes normalized device coordinate space where the direction from object to viewer is 
always (0.0, 0.0, —1.0). Hence, to place the light source at the viewer, the light direction is 
(0.0, 0.0, —1.0). The light direction vector is only used if the shading style is GOURAUD or 
PHONG. A useful light direction is (—0.2, 0.2, —1.0). 

5.8.3. set_vertex_norma 1 s 

set_vertex_normals sets the surface normal vectors for each vertex of the subsequent 
three-dimensional polygon primitives (polygonabs_3 or polygonrel_3). These normals are 
used for PHONG style shading. For GOURAUD style shading, use set_vertex_indices. 

set_vertex_normals(xlist^ ylist^ zlist, n) 
float xlist [], ylist [], zlist []; 
int n; 

The number of elements in the list, n, must be equal to the number of vertices in the subsequent 
call to polygonzzz_3. 


5.8.4^ set_vertex_indices 

set_vertex_indices specifies a color index for each vertex of the next polygona:a:x_3 
primitive. GOURAUD shading linearly interpolates these color indices for smooth shading in the 
interior of the polygon. 
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set_vertex_indices (color_index_lis1:, n) 
int color_indox_llst []; 
int n; 

The number of elements in the list, n, must be equal to the number of vertices in the subsequent 
call to polygonxxx_3. 


5.8.5. set_zbuf fer_cut 

set_zbuf fer_cut specifies a cutaway view of 3-D polygon objects when hidden surfaces are 
being removed. se't_zbu f fer_cut specifies an array of depths in Normalized Device Coordi¬ 
nate space. Any parts of objects which are closer to the viewer than this piecewise-linear func¬ 
tion are clipped away. 

set_zbuffer_cut(surface_name, xlist^ zllst, n) 

struct vwsurf *surfaco_namo; /* See appendix B */ 

float xlist[], zlist[]; 
int n; 

xliit is assumed to be monotonically increasing. This function specifies a piecewise-linear cutar 
way threshold in the z coordinate, which, given any x coordinate, is constant in y. The default 
cutaway depth is 0 for all values of x. Values of x less than a:fMf(0] or greater than xli8t[n - 1] 
will have the default depth. The view surface must have been initialized with the hidden flag 
on. 


5.9. Polygon Functions (SunCore Extension) 

The polygon functions are a SunCore extension to the ACM Core specification. The polygon 
functions describe connected sequences of lines which form closed figures. The polygons are 
filled in with color as specified by the set_fill_index primitive attribute, or are shaded 
according to the current shading parameters, depending on the polygoniiTterior_st:yle 
primitive attribute. Only polygons created by the three-dimensional polygon functions may be 
shaded. 

The first two or three arguments to a polygon function are arrays of the appropriate coordinates. 
Consider the polygon function: 

polygon_abs_3 (x_array, y_array, z_array, n) 

float x_array[3, Y—ai^r*ay[], z_array[]; /* x, y, and z coordinates */ 
int n; /* Number of coordinates */ 

The bounding sequence of edges that these arrays of coordinates describe pass from the first 
point (z_array[0], j/L.arr<iy[0], z_arfay[0]), then runs through the intermediate array values to 
(x_array[n—l], y_array(n—1], ^_array [n—1]), and then back to the first point, n is the number 
of elements in each of the coordinate arrays. There are thus n sides in the figure described. 

Note that the polygon functions describe a closed figure. The last coordinate in the array of 
points is connected to the first point. 

Error Codes from the Polygon Functions: 
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• The number of coordinates, n, is less than or equal to two. 

• There is no open segment. 


5.9.1. polygon_abs_2 — Describe Polygon in Absolute 2D Coordinates 

polygonabs_2 describes a polygon in absolute two-dimensional world coordinates. 

polygon_abs_2(x_array, y^array, n) 

float x_array[], y_array[]; /* x and y coordinates */ 

int n; /* number of array elements */ 

The Current Position is set to the first point. 


5.9.2. polygon_abs_3 —Describe Polygon in Absolute SD Coordinates 

polygonabs_3 describes a polygon in absolute three-dimensional world coordinates. 

polygon_abs_3(x_array, y_array, z_array, n) 

float x_array[], y_array[], z_array[]; /* x, y, and z coordinates */ 
int n; /* number of array elements */ 

The Current Position is set to the first point. 



5.9.S. polygon_rel_2 — Describe Polygon in Relative 2D Coordinates 

polygonrel_2 describes a polygon in relative two-dimensional world coordinates. The first 
array value specifies a displacement from the Current Position; remaining array values specify 
displacements from the preceding point. 

polygon_rel_2(dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y deltas */ 

int n; /* number of array elements */ 

The Current Position is set to the first point. 


5.9.4- pcilygon_rel_3 — Describe Polygon in Relative SD Coordinates 

polygonrel_3 describes a polygon in relative three-dimensional world coordinates. The first 
array value specifies a displacement from the Current Position; remaining array values specify 
displacements from the preceding point. 

polygon_rel_3(dx_array, dy_array, dz_array, n) 

float dx_array[], dy_array[], dz_array[]; /* x, y, and z deltas */ 
int n; /* number of array elements */ 

The Current Position is set to the first point. 


o 
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5.10. Raster Primitive Functions (SunCore Extension) 


5.10.1, put_raster — Raster Output Primitive 

put_raster draws a rectangular 1-bit or 8-bit deep raster and enters it into the current seg¬ 
ment. The raster may not be used in transformable segments, because rasters cannot be scaled 
or rotated in the current release of SunCore. A raster primitive may, however, be picked or 
dragged if it is entered in a translatable segment. The Current Position is at the lower left-hand 
corner of the raster. 

Note that put_rast:er is device dependent in that it is written to the right and upward from 
the Current Position a specified number of PIXELS in height and width. The Current Position is 
unchanged. 

put_raster(raster) 
struct { 

int width, height, depth; 
short *bits; 

)• ‘raster; 

The depth parameter can be 1 or 8 bits per pixel. 

The bits of the raster are stored in the following order tor depth =» 1: The first word is the upper 
left 16 horizontal bits, with the high order bit being the leftmost bit. The first (toirf<A-f-15)/16 
words comprise the top row of the rectangle. The number of words of storage that bits points to 
is: 


{(mdth*15) / 16) * height 
for depth = 1. 

Rasters of depth = 8 are stored as successive bytes in row order. The number of bytes that bits 
points to is: 

width height 
for depth = 8. 

If a 1-bit deep raster is written to a color view surface, ‘0’ bits select the background color and 
*1’ bits select the color specified by the fill index primitive attribute. 

Note that output clipping is always done on raster primitives. 

5.10.2. get_r aster — Read Raster from Black/White or Color Frame Buffer 

get_raster reads a specified region of the black and white or color frame buffer into a storage 
area. 
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get_raster (surfactt_naiM« xmin, xmax, ymin« ymax, x« y, raster) 

struct vwsurf *8urface_name; /* See appendix B */ 

float xnin, ymin, xmax, ymax; /* Region of NDC space to get */ 
int X, y; /* starting point pixel offsets in raster relative top left */ 
struct ■( 

int width, height, d^th; 
short *bits; 

} ‘raster; /* Returned Raster */ 

get_rkster requires an area of memory large enough to hold the raster region that it returns. 

It is the user’s responsibility to allocate this storage area before calling get_raster. The 
size_rastor and allocate^raster functions may be used to do this: 

size^raster(surface_naiDe, xmin, xmax, ymin, ymax, firaster); 
allocate^raster(&raster); 

If (raster.bits == NULL) 

error case — the raster could not be allocated 

else 

continue with the processing 

To free the area when finished with the raster, call the froo_raster function: 
free_raster(&raster); 

Hence, a large raster may be allocated and then portions of it filled with data using 
get_raster with various x, y offsets, in pixel coordinates from the top left hand corner of the 
raster. 


5.10.3. size_raster — Set Size of Raster in NDC 

size_raster returns the raster with the pixel coordinates ixfidth, height, and depth, for a 
specified region of Normalized Device Coordinate space and a specified view surface. 

sizo_raster(surface_naine, xmin, xmax, ymin, ymax, raster) 
struct vwsur f ‘sur face^name; 
f 1 oat xmin, xmax, ymin, ymax; 
struct •{ 

int width, height, depth; 
short ‘bits; 
y ‘raster; 

On return, rasterMts is set to NULL. 


5.10.4- allocate_raster — Allocate Space for a Raster 

Given a raster whose width, height, and depth fields were filled by the size_raster function 
(described above), allocate_raster allocates the memory required for that raster and sets 
the ra$ter,bits pointer. 
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allocato_rastor(raster) 
struct •{ 

int width, height, depth; 
short *bits; 

} ‘raster; 

allocate_raster returns a NULL pointer value in ra»ter,bit$ if it is unable to obtain enough 
memory for the raster structure. 


5,10.5. free_raster — Free Space of a Raster 

free_rastor frees the memory used by a specified raster, if raster •bit* is not NULL. 

free_raster(raster) 
struct { 

int width, height, depth; 
short ‘bits; 

} ‘raster; 


5.10.6, raster_to_file — Copy a Raster to a Disk Raster File 


rastor_to_file copies a raster to a disk file in Sun’s standard raster file format. 


raster_to_file(raster, map, 
struct ■{ 

int ■ width, height, 
short ‘bits; 

}• ‘raster; 
struct ■{ 

int type; /‘ 

int nbytes; /‘ 

char ‘data; /‘ 

} ‘map; 

int td; /* 

/* 

/* 

int replicate; /‘ 


fd, replicate) 
depth; 


1 for RGB color table ‘/ 

3 times number of color table elements ‘/ 
ptr to nbytes/3 rod, blue, and green bytes ‘/ 

standard UNIX file descriptor for C programs ‘/ 
FORTRAN logical unit number for FORTRAN programs 
Pascal file variable for Pascal programs ‘/ 
magnification factor ‘/ 


If map.nbytes - 0, no color map data will be written. This would normally be the case for ras¬ 
ters copied from the bitmap display. 


The replicate parameter specifies whether the raster should be magnified on transmission to the 
file. The raster is transmitted without magnification if replicate — 1, and is transmitted with 
pixel-replication zoom for a factor of 2 rhagnification if replicate »■ 2. 

The format of the generated disk file can be found in the include file in 
/usr/include/rasterfile.h. Disk raster files can be printed on a Versatecjike ploter device by 
using the /pr(l) command with the — v option. 
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5.10.7, file_to_raster — Get a Raster from a Disk Fite 

file_t:o_raster allocates enough memory for a raster stored on a disk file, then fills in all 
fields of the raster and map structures. 

file_to_rast:or (fd, raster^ map) 

int fd; /* standard UNIX file descriptor for C programs */ 

/* Fortran logical unit number for Fortran programs */ 

/* Pascal file variable for Pascal programs */ 

struct ■( 

int width, height, depth; 
short *bits; 

} *raster; 

struct ■{ 

int typo; /* 1 for RGB color table */ 

int nbytes; /* 3 times number of color table elements */ 
char *data; /* ptr to nbytes/3 red, blue, and green bytes */ 

> *map; 

Note that this function frees map,data, unless data is NULL, and allocates map.data each time 
it is called — therefore map,data is only valid in the last call to this function. The raster.bits 
field is set to NULL if there is not enough room to allocate the raster. 

The format of the disk file can be found in the include file in fusrj include f raster file,h. 




Revision F of 15 May 1985 


5-19 













o 


Chapter 6 
Attributes 




Attributes in SunCore specify general characteristics for segments and for output primitives. 

There are two major divisions of attributes. One set of attributes is called segment attributes 
and applies only to retained segments. The other set is called primitive attributes and applies 
only to output primitives. There are no attributes which apply to both retained segments and to 
output primitives. 

Attributes are further subdivided into static and dynamic. Static attributes specify characteris¬ 
tics of retained segments or output primitives which apply for the entire lifetime of those 
objects. Dynamic attributes specify characteristics of segments which can change during the life¬ 
time of those segments. Static primitive attributes are stored in the display list so that subse¬ 
quent manipulation of a segment is performed with the appropriate attributes. 


6.1. Primitive Static Attributes 

The list below defines the primitive static attribute values. 
line index 

is fin index into three float arrays which determine the red, green, and blue components 
of the color displayed for line and polyline output primitives. Index value 0 corresponds to 
thej background color. For lines and polylines on monochrome displays, a non-zero line index 
givps black lines on a white background. SunCore initializes line index to 1. The range of 
possible values is 0 to 255. 

fill index 

is an index into three float arrays which determine the red, green, and blue components 
of the color displayed for polygon and raster output primitives. Index value 0 corresponds to 
the background color. For monochrome displays, the values form a set of definitions for tex¬ 
ture, described later. SunCore initializes fill index to 1. The range of possible values is 0 to 
255. 

text index 

is an index into three float arrays which determine the red, green, and blue components 
of the color displayed for markers and text. Index value 0 corresponds to the background 
color. For text and markers on monochrome displays, a non-zero text index gives blaqk on a 
white background, SunCore initializes text index to 1. The range of possible values‘’is 0 to 
255. 
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line style 

is an in-t value which controls the appearance of lines drawn. Linestyle can assume the 
values; 

SOLID Solid lines, 

DOTTED Dotted lines, 

DASHED Dashed lines, 

DOTDASHED 

Dotdashed lines. 

The definitions of these constants can be found in usercore*h. SunCore sets linestyle to 
SOLID at initialization time. 

polygon interior style 

is an int value which controls the interior filling style for polygons, polygon interior 
style can have the values: 

PLAIN Solid color polygon 

SHADED Shading style is set dynamically by se‘t_shading_paraiii©ters. Only 
3-D polygons may be shaded. 

SunCore sets polygon inferior style to PLAIN at initialization time. 
polygon edge style 

is not implemented in the current release of SunCore. 

linewidth is a float value which describes, in world coordinates, the width of drawn lines. 
SunCore sets linewidth to 0.0 (the minimum) at initialization time. 

pen is an int value which is passed to the device driver to select a particular device 

dependent pen. SunCore initializes pen to 0. 

font is an int value which determines the character font in which text will be written. 

Font can assume the following values (for cAcrprcciaion=CHARACTER): 

ROMAN If cAarprcci«ion= STRING, this gives a large raster font. 

GREEK If cAorprecMiorj=STRING, this gives the default raster font. 

SCRIPT If cA(irpreciaton=STRING, this gives a small raster font, 

OLDENGLISH If cAarprccwion=STRING, this is equivalent to a bold version of GREEK. 

STICK If cA(irprecwion=STRING, this is equivalent to a medium sized ROMAN 

raster font. 

SYMBOLS Currently holds some electronics symbols (character values 32 through 
47). If cA«rprccMinn=STRING, this is equivalent to a bold version of 
STICK. 

SunCore sets font to STICK at initialization time. 

charsize is a pair of float values which determine the size of characters, in world coordi¬ 
nates. SunCore sets the default character width to 11.0 and the default character 
height to 11.0 at initialization time. 

charvp attribute consists of three float values which represent a vector giving the direc¬ 
tion of ‘up’ for characters: 
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{dx^charup, dy^charup, dz^charup) 

in world coordinates. Usually, champ is normal to ckarpatk. SunCore establishes the default 
as a vector in the positive y direction (0.0, 1.0, 0.0) at initialization time. 

ckarpath 

consists of three float values which represent a vector: 

{dx^charpath, dy^charpath, dz^charpatk) 

that determines the direction, in world coordinates, in which character strings will extend. Sun- 
Core sets the charpath attribute to (1.0, 0.0, 0.0) at initialization time. 

charspace 

is a single float value specifying the space, in world coordinates, which should be inserted 
between characters in a text string. SunCore establishes charspace with the value 0.0 at 
initialization time. 

char just 

is not implemented in the current release of SunCore. 
charprecision 

is an int value which controls the quality of the text drawing operation. Charprecision can 
have the values: 

STRING Fast raster fonts, fixed size, and fixed orientation. 

CHARACTER Hershey vector fonts. 
marker^symbol 

determines the character which is plotted on the displays by the marker and polymarker 
functions described in the chapter on Output Prtmtttves, Any printable ASCII character can 
be used as the marker character. 

Note: The ACM Core specifies that the integer values 1 through 5 represent specific charac¬ 
ters. SunCore does not implement this feature. 

pich^id 

is an int value identifying the next output primitive. The input primitives use this number 
for user interaction with segments and primitives within segments. 

rasterop 

specifies the rasterop used when writing to the display. It can be one of: 

NORMAL Source value is written to the display. 

XORROP Source value is exclusive or’ed with the value already in the display before being 
written to the display. 

ORROP Source value is or’ed with the value already in the display before being written to 
the display. 

This attribute is ignored if set_drag was specified as TRUE. 

The functions listed in the subsections below each set the specified attribute value for the indi¬ 
cated primitive attribute. 

Errors returned from the primitive attribute setting functions: 
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• One or more of the attribute values is incorrect. 

• No character orientation can be established because dz^charpath^ dy_ckarpath, and 
dz^charpath are all zero. 

• No character up direction can be established because dz^ckarup, dy_charup, and 
dz_charup are all zero. 


6.1.1. Using Texture for Color Attributes on the Monochrome Display 

When a monochrome display is used, the fill index attribute is used to determine how a region of 
the screen is textured when using the polygon output primitives. Texturing is done in terms of 
16 X 16 pixel regions of the screen. There are 16 rows of 16 pixels each. The fill index attribute 
selects an entry from each of three arrays of float values in the range 0.0 through 1.0, 
representing red, green, and blue. In the case of the monochrome display, each of these three 
float numbers is converted to an integer between 0 and 255. Each of the 8-bit numbers is 
divided into two four-bit quantities, which we can call A and B. 


Table 6-1: Structure of a Fill-Index Value 


Red 

Green 

Blue 

Select 

B 

Select 

A 

Length 

B 

Length 

A 

Rotate 

B 

Rotate 

A 


Select A and Select B are four-bit values which are used to select an A pattern and a B pattern 
out of the table of numbers shown below. 
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Table 6-2: Texture Selection Values 


Four-Bit 

Value 

Hexadecimal 

Pattern 







Binary Pattern 







0 

0000 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1 

8000 

1 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

2 

8080 

1 

0 

0 

0 

0 

0 

0 

0 

1 

0 

0 

0 

0 

0 

0 

0 

3 

8410 

1 

0 

0 

0 

0 

1 

0 

0 

0 

0 

0 

1 

0 

0 

0 

0 

4 

8888 

1 

0 

0 

0 

1 

0 

0 

0 

1 

0 

0 

0 

1 

0 

0 

0 

5 

9124 

1 

0 

0 

1 

0 

0 

0 

1 

0 

0 

1 

0 

0 

1 

0 

0 

6 

9494 

1 

0 

0 

1 

0 

1 

0 

0 

1 

0 

0 

1 

0 

1 

0 

0 

7 

A552 

1 

0 

1 

0 

0 

1 

0 

1 

0 

1 

0 

1 

0 

0 

1 

0 

8 

AAAA 

1 

0 

1 

0 

1 

0 

1 

0 

1 

0 

1 

0 

1 

0 

1 

0 

9 

EB6E 

1 

1 

1 

0 

1 

0 

1 

1 

0 

1 

1 

0 

1 

1 

1 

0 


DDDD 

1 

1 

0 

1 

1 

1 

0 

1 

1 

1 

0 

i 

1 

1 

0 

1 


F7F7 

1 

1 

1 

1 

0 

1 

1 

1 

1 

1 

1 

1 

0 

1 

1 

1 

12 

FFFF 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

13 

E3E3 

1 

1 

1 

0 

0 

0 

1 

1 

1 

1 

1 

0 

0 

0 

1 

1 

14 

FFOO 

1 

1 

1 

1 

1 

1 

1 

1 

0 

0 

0 

0 

0 

0 

0 

0 

15 

OOFF 

0 

0 

0 

0 

0 

0 

0 

0 

1 

1 

1 

1 

1 

1 

1 

1 


The patterns are then laid down in the texture field, pixels, as described in the pseudo code 
below. 
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let X = y = Pattern A 
for index = 0 to Length A - 1 
pixels[index] = z \ y 

if Rotate A & 1 then rotate x one bit right 

if Rotate A & 2 then rotate x one bit left 

if Rotate A & 4 then rotate y one bit right 

if Rotate A & 8 then rotate y one bit left 

let X = y = Pattern B 

for index = Length A to Length A + Length R - 1 
pixels [index] = a; | y 

if Rotate B & 1 then rotate x one bit right 

if Rotate B & 2 then rotate x one bit left 

if Rotate B & 4 then rotate y one bit right 

if Rotate B & & then rotate y one bit left 

If the value of 

length A + length B 

is less than 16, the processes described above are repeated as many times as required to fill the 
16 line region. 

The above encoding provides for an enormous number of textures. Here are a few of the useful 
ones. 


Table 6-3: Useful Texture Selection Values 


Red 

Value 

Green 

Value 

Blue 

Value 

Resultant 

Texture 

0.1334 

0.5020 

0.3529 

Hatched Left 

0.1334 

0.5020 

0.6471 

Hatched Right 

0.4667 

0.5334 

0.2118 

Wallpaper 

0.0000 

0.2667 

0.3882 

Black 

0.8001 

0.2667 

0,4001 

White 

0.1334 

0.3334 

0,4001 

Wavy Lines 

0.5334 

0.5334 

0.4001 

Grey Tone 

0.1334 

0.5334 

0.4001 

Cross Hatched 


6.1,2. define_color_indices — Assign Colors to Indices 
define_coloT_indices defines entries in the color lookup table of a view surface. 
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define_color_indices(surface_name, il, 12, red_array, green_array, blue^array) 
struct vwsurf *surfaco_namo; /* See appendix B */ 

int 11, 12; /* indices range from 0 through 255 */ 

float red_array[], green_array [], blue_array[]; 


The three arrays provide the values for red, green, and blue respectively. The value of each ele¬ 
ment in the color arrays is in the range 0.0 through 1.0. The function defines all the indices in 
the color index table between il and i2 inclusive, using the first \ elements from each of 

the three arrays. 

Subsequent calls to the set_zM_index function selects a color from the lookup table to use ss 
a color attribute. 

Location 0 in the color tables is the background color for the view surface. For the monochrome 
displays, lines, text, and markers are drawn black for any color index other than 0. 

SunCore initializes the lookup table for monochrome view surfaces such that for the ith entry, 
red[»] = I, green[i] = 255- 1, and blue[i] = i. SunCore initializes color view surfaces which have a 
full 256-element lookup table such that entry 0 is gray, entry 1 is black, entries 2 through 63 
contain an intensity ramp in red, entries 64 through 127 contain an intensity ramp in green, 
entries 128 through 191 contain an intensity ramp in blue, and entries 192 through 255 contain 
an intensity ramp in yellow (red-hgreen). See appendix B for details of color view surfaces with 
fewer than 256 entries in the lookup table. 


6.1.S, set_line_index — Select a Line Color Attribute 

sGt_line_index selects a color by providing an index into the tables defined by the 
define^color^indices function. This color attribute is applied to subsequent line and polyline out¬ 
put primitives. 

sGt_linG_index(indGx) 

int indGx; /* range 0 through 255 */ 


6.1.4. set„fill_index — Select a Polygon and Raster Color 

set_fil l_index selects a color by providing an index into the tables defined by the 
define^color_indicea function. This color attribute is applied to subsequent polygon and raster 
output primitives. 

set_fill_index(index) 

int index; /* range 0 through 255 */ 
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6.1.5. set_text_index — Select a Text and Marker Color 

set_text_index selects a color by providing an index into the tables defined by the 
define_color^tndtce8 function. This color attribute is applied to subsequent text and marker out^ 
put primitives. 

set_text_index(index) 

int index; /* range O through 255 */ 


6.1.6. set_linewidth 

set^linewidth specifies the linewidth attribute for the output primitives. 
set_linewidth(1inewidth) 

float linewidth; /* unit of width is 1 percent of NDC space */ 

SunCore initializes linewidth to 0.0, which results in a one pixel wide line. 

If XOR’ing is enabled (via the set_r aster op or set_drag functions), lines whose pixel 
width is greater than one may partially overwrite themselves, resulting in poorly drawn wide 
lines. Redrawing the lines with XOR’ing off will draw the lines correctly (until this problem is 
fixed). 


6.1.7. set_linestyle 

set_linestyle specifies the linestyle attribute for output primitives. 

set_linestyle (linestyle) 

int linestyle; /* SOLID, doited, */ 

/* DASHED, DOTDASHED */ 


SunCore initializes linestyle to SOLID. 


6.1.8. set_polygon_int:er ior_style — Select Plain or Shaded Polygons 

set_polygon_in'terior_s'tyle specifies the method of filling for polygons. 

set_polygon_interior_style (style) 

int style; /* plain, shaded */ 

If the filling method is SHADED, polygons are shaded according to the parameters set by the 
set_shading_parainet:ers function. Only 3-D polygons may be shaded. 
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6.1.9, set:_polygon_edge_style (No Effect) 

set_polygon_edge_stylo specifies the method of drawing the edges of a polygon. 

set„polygon_edge_style (style) 

int stylo; /* solid , interior */ 

This function has no effect in the current release of SunCore. 


6.1.10. set_font 

set_font specifies the font attribute for the output primitives. 
set_font(font) 

int font; /* roman, greer, script */ 

/* OLDENGLISH, STICR, SYMBOLS */ 


SunCore initializes font to STICK. If the charprecision attribute is set to STRING, ROMAN gives 
a small Roman font, GREEK gives a stick figure font, SCRIPT gives a tiny stick figure font, OLDEN¬ 
GLISH gives a bold version of GREEK, STICK gives a medium sized ROMAN raster font, and SYM¬ 
BOLS gives a bold version of STICK. The STRING precision fonts are ‘raster’ fonts and are not 
scalable or rotatable, hence they are in pixel coordinates and are larger on the color surface than 
on the monochrome bitmap display. 


6.1.11. set_pen — Select a Device Dependent Pen 

This function has no effect on the standard SunCore view surfaces. 

set_pen(pen) 
int pen; 


6.1.12. set_charsize 

set_charsizo specifies the char^ize attribute for the text output primitive, in world coordi¬ 
nates. 


set_charsize (charwidth, charhoight) 
float charwidth, charhoight; 


If the charprecision attribute is set to STRING, set_charsizo has no effect, except to control 
the target extent of the text for the await_pick function. If the charpreciiion attribute is set to 
CHARACTER, set_charsize sets the average size of a character, given that each character has 
its own size. 
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6.1.IS. set_charspace — Define Character Spacing for Output Primitives 

set_charspace specifies the space attribute for the text output primitive, in world coordi¬ 
nates. It is used to insert additional space between characters in text strings. 

set_charspaco(charspace) 
float charspace; 


If the charprecision attribute is set to STRING, set_charspace has no effect. 


6 . 1 . 14 . set_charup„2 

set_charup_2 specifies the ckarup attribute for the text output primitive, in world coordi¬ 
nates. 


set_charup_2(dx, dy) 
float dx, dy; 

Note that the dz offset is set to 0,0 for this function. If the ckarpredsion attribute is set to 
STRING, set_charup_2 has no effect; otherwise it specifies the upward direction for the char¬ 
acters. This provides for slanting, mirror imaging, and so on, for characters. 


6.1.15. set_charup_3 

set_charup_3 specifies the charup attribute for the text output primitive, in world coordi¬ 
nates. 


set_charup_3 (dx, dy, dz) 
float dx, dy, dz; 

If the charprecision attribute is set to STRING, set_charup_3 has no effect; otherwise it 
specifies the direction of upward for the characters. This provides for slanting, mirror imaging 
and such, for characters. 


6.1.16. set_charpath_2 

set_charpath_2 specifies the ckarpath attribute for the text output primitive, in world coor¬ 
dinates. 


set_charpath_2 (dx, dy) 
float dx, dy; 


Note that the dz offset is set to 0.0 for this function. If the charprecision attribute is set to 
STRING, set_charpath_2 has no effect; otherwise the character string is written in this direc¬ 
tion. 


6-10 


Revision F of 15 May 1985 









SunCore Reference Manual 


Attributes 


6.1.17. set_charpath_3 

set„charpath_3 specifies the ckarpath attribute for the text output primitive, in world coor¬ 
dinates. 


set_charpath„3 (dx, dy, dz) 
float dx, dy, dz; 

If the charprecision attribute is set to STRING, sot_charpath_3 has no effect; otherwise the 
character string is written in this direction. 

6.1.18. set_char just — Specify Text Justification (No Effect) 

set_charjust specifies how text strings should be justified. 

set^char just (just) 
int just; 

This function has no effect in the current release of SunCore. 


6.1.19. set_charprecision 

set^charprecision selects the method of drawing text. 

set_charprecision(charprecision) 

int charprecision; /* STRING, character */ 

STRING Specifies characters of fixed size and orientation, which are drawn rapidly using 

raster operations. This is the default. 

CHARACTER Specifies Hershey vector fonts, which can be clipped and transformed. 

6 .1.20. set_marker_syTnbo 1 

set_markor_syinbol establishes the marAcr_«ym6o/primitive attribute. 
set_marker_syinbol (marker) 

int marker; /* Character to use as Marker — 32 . . 127 */ 

The character specified by the marker argument in the set_marker_syiDbol function call is 
subsequently used as the marker character by the marker and polymarker functions. 
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6,1.21. set_pick_id 

set_pick_id specifies the pick_id attribute for output primitives. 

set_pick_id (pick^id) 
int pick_id; 


The pick_id attribute is only used by the await_pick input function. Subsequent output primi¬ 
tives are identified by the specified pick_id when they are detected by the mouse pointing device, 
via the ttwait_pick input function. 


6.1.22. set_rasterop — Select Rasterop to Display Memory (SunCore Extension) 
set_rasterop selects XorMng or or’ing of primitives to display memory. 
set_rasterop (rop) 

int rop; /* xorrop, orrop, normal */ 


6.1.23. set_primitive__attributes — Specify All Primitive Attributes 

set_primitive_attributes is a composite function which provides a means to set all the 
primitive attributes in a single function call. 

set_priniitive_attributes (attributes) 
struct { 

int lineindx, fillindx, textindx; 

int linestyl, polylinestyl, polyedgestyl; 

float 1inwidth; 

int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

)• * attributes; 

Note that the function call: 

‘set_primitive_attributes (&PRIMATTS) 

sets allithe primitive attributes to their default values. PRIMATTS is defined in usercore*h. 
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6.2. Inquiring Primitive Static Attribute Values 


Errors returned from the primitive static attribute enquiry functions: 

• A two dimensional inquiry function was used when a three dimensional inquiry function 
should have been used to avoid loss of information. 


6 . 2 . 1 . inqiiire_color_indices 

inquiro_color_indices obtains the color lookup table for the specified view surface. 

inquiro_color_indices(surface_namo, il, 12, red_array, green_array, blue_array) 
struct vwsurf *surface_name; /* See appendix B */ 

int 11, 12; /* Start and end table indices */ 

float red_array[]; /* Range of each element is 0.0 thru 1.0 */ 

float green_array[]; /* Range of each element is 0.0 thru 1.0 */ 

float blue_array[]; /* Range of each element is 0.0 thru 1.0 */ 

»urface_name is the name of the view surface for which the color lookup tables should be 
obtained. 

inquire_color_indices takes entries from the color lookup tables, starting at index il 
(relative to zero) and ending at index i2. The color lookup tables for a given color are stored in 

orray[0] through orroy 


6 . 2 . 2 . inquire_line_index 

inquire_line_index obtains the current color index for coloring line and polyline output 
primitives. 

inquire_lino__index (index) 
int ‘index; 


6 . 2 . 3 . inquire_fill_index 

inquire_fil l_index obtains the current color index for coloring polygon and raster output 
primitives. 

inquiro_fill_index (index) 
int ‘index; 
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6.2.4- inquire_text_index 

inquire_-text_index obtains the current color index for coloring marker and text output 
primitives. 

inquiro_'text_index (index) 

Int ‘index; 


6.2.5. inquire_linewidth 

inquire,.linewidth obtains the Unewidth attribute, in percent of normalized device coordi¬ 
nate space, for the output primitives. 

inquire_linewidth(1inewidth) 
float *1inewidth; 


6.2.6. inquire_linestyle 

inquire_linestylo obtains the linestyle attribute for the output primitives. 

inquire_linestyle (linestylo) 

int ‘linestyle; /* solid, doited, */ 

/* DASHED, DOXDASHED */ 


6.2.7. inquire_polygon_interior_style — Obtain Polygon Shading Method 

inqui^e.,polygon__interior_sty le obtains the method of filling for polygons. 

inquire_polygon_interior_style (style) 

int ‘style; /* PLAIN, SHADED */ 


6.2.8. inquire_polygon_edge_style 

inquire_polygon_edge_style obtains the current method of drawing polygon edges. 

lnquire_jpolygon_edge_style (style) 

int ‘style; /* SOLID, interior */ 


6-14 


Revision F of 15 May 1985 



SunCore Reference Manual 


Attributes 


6 .2.9. ir^quire_pen 


inquire_pen(pen) 

int *pen; /* Device dependent pen selector */ 


6 .2.10. inquire., font 

inquire^font obtains the font attribute for the text output primitive. 
inquire_font(font) 

int ‘font; /* ROMAN, GREEI, SCRIPT, OLDENGLISH, */ 

/* STICr, SYMBOLS */ 


6 .2.11. inquire_charsize 

inquire_charsize obtains the charstze attribute for the text output primitive. 

inquiro..charsize (charwldth, charheight) 
float *ch.arwidth, *charheight; 


6 .2.12. inquire_charspace 

inquire_charspace obtains the chorspoce attribute for the text output primitive. 

inquir eschar space (char space) 
float * charspace; 


6.2.13. inquire_charup_2 

inc[uire_charup_2 obtains the champ attribute for the text output primitive. 

inquire_charup_2(dx, dy) 
float *dx, *dy; 


6.2.14. inquire_charup_3 

inquire_charup_3 obtains the champ attribute for the text output primitive. 

inquire_charup_3(dx, dy, dz) 
float *dx, *dy, *dz; 
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6.2.15. inquire_charpath_2 

inquire_charpa-th_2 obtains the charpatk attribute for the text output primitive. 

inquiro_charpath_2(dx, dy) 
float *dx, *dy; 



6.2.16. inquire_charpath_3 

inquife_charpath_3 obtains the charpath attribute for the text output primitive. 

inquire,.charpath_3 (dx, dy, dz) 
float *dx, *dy, *dz; 


6.2.17. inquire_char just; — Obtain Justification Attribute 

inquire_ch.ar just obtains the justification attribute for text strings. 

inquire_charjust(just) 
int *just; 


6.2.18. inquire_r aster op — Obtain Current Rasterop (SunCore Extension) 
inquire^rasterop determines the current setting of the rasterop attribute. 
inquire_rasterop(rop) 

int * r op; / * XORROP, orrop , normal * / 



6.2.19. inquire_charprecision 

inquire_charprecision obtains the ckarpreciston attribute for the text output primitive. 

inquire_charprecision(charprecision) 

int *charprecision; /* STRING, character */ 


6.2.20. inquire_pick_id 

inquire_pick_id obtains the pick^id attribute for output primitives. 

inquire_pick_id(pick_id) 
int *pick_id; 
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6 .2.21. inquire_marker_symbol 

inquire_marker_symbol obtains the current value of the marker symbol. 

inquire_jnarker_synibol (symbol) 

int ^symbol; /* 32 .. 127 */ 


6 .2.22. inquire_priinitive_attributes — Obtain All Primitive Attributes 

inquire_primitive_attributes is a composite function which provides a means to obtain 
all the primitive attributes in a single function call. 

inquire_primitiv©_attributes(attributes) 
struct ■{ 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float linwidth; 
int pen, font; 
float charwidth, charheight; 
float charupx, charupy, charupz, charupw; 
float charpathx, charpathy, charpathz, charpathw; 
float charspacex, charspacey, charspacez, charspacew; 
int chjust, chquality; 
int marker, pickid, rasterop; 
y ‘attributes; 


6.3. Retained Segment Static Attributes 


There is only one static attribute for segments. This is the image^transformation^tf/pe attribute. 
This attribute can take on one of five values: 


NONE Retained segment on which no translation, scaling, or rotation can be performed. 

XLATE2 Translatable retained segment. The segment can be moved (translated) in two 
dimensions (x and y of NDC space), 

XFORM2 Fully transformable retained segment. The segment can be moved (translated), 
rotated, and scaled (have its size changed) in two dimensions (x and y of NDC space). 


XLATE3 Translatable retained segment. The segment can be moved (translated) in three 
dimensions (x, y and z of NDC space). 

XFORM3 Fully transformable retained segment. The segment can be moved (translated), 
rotated, and scaled (have its size changed) in three dimensions (x, y and z of NDC 
space). 


The image^transformation^type attribute is set when a segment is created and cannot be 
changed at any time during the life of the segment. The default value of 
image_transformation^type is NONE. 
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The functions described below are used to set and enquire about the values of 
imagejtransformation^typc. 


6 .3.1. s e t_ ima ge_ t r an s f or mat i on_type 

set_image_transformation_type specifies the image^tramformation^type attribute for 
subsequently created segments. 

sot_imago_trans format ion_typo (typo) 

int type; /* NONE, XLATE2, XF0RM2, XLATE3, XFORM3 */ 


6 .8.2. inquire.image_transformation.type 

inc[uire_image.trans format ion. type obtains the current value of t 

imagtJtransforfnation_typt attribute. 

inquiro.imago.trans format ion.typo (type) 

int ‘type; /* NONE, XLATE2, XF0RM2, XLATE3, XF0RM3 */ 


6 .3.8. inquire.segment.image.trans formation.type 

inquire.segment_image.transformation.type obtains the imdgc^ittinifoftnation^typti 

for a specified segment. 

inquire.segment.image.transformation.type(segment.namo, type) 

int segment.name; /* Name of segment for inquiry */ 

int ‘type; /* NONE, XLATE2, XF0RM2, XLATE3, XF0RM3 */ 


6.4. Setting Retained Segment Dynamic Attributes 

In addition to the one static attribute described above, there are a number of dynamic attributes 
which apply to segments. Each retained segment has its own set of dynamic attributes, as listed 
below. 

Visibility indicates whether the segment should have a visible image. There are only two 
values of this attribute, namely: TRUE and FALSE. 

SunCore sets visibility to TRUE at initialization time. 

Highlighting indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by briefly blinking the segment. There are only two values of 
the highlighting attribute, namely, TRUE and FALSE. 

SunCore sets highlighted to FALSE at initialization time. 

Detectability indicates whether the retained segment can be detected by the await^pick input 
primitive. A value of 0 means that the segment is not pickable. If two segments 
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overlap, the one with the greatest value of deteetability is the one that gets picked. 
SunCore sets detectability to the default value of 0 at initialization time. 

ImageJtransformation 

indicates how the image of a retained segment is scaled, rotated, or translated. 
Image transformations are done in NDC space, that is, after all viewing operations 
have been performed. Image transformations do not compose and do not cumu¬ 
late. Whenever any function affecting a segment’s image transformation is called, 
the transformation is reset to reflect only the values specified by the call. The 
imageJtramformation attribute of a segment must be consistent with its 
imagejtransformationjtype attribute (for instance, if the 
image_transformation_type is XLATE2, it is an error to attempt to rotate the seg¬ 
ment). 

SunCore sets the default image_tran9formation to the identity transformation 
(that is, no translation, scaling, or rotation) at initialization. 

There are two classes of functions for setting retained segment dynamic attributes. One class 
sets the default attributes for subsequently created segments; the other sets attributes on a 
named segment basis. 

Errors which can be returned from the retained segment dynamic attribute setting routines are: 

• There is no retained segment called Aegment^name. 

• One or more of the attributes is incorrect. 

• The segment’s image_tran 9 formation_type attribute value is incompatible with the 
requested function. 


set_visibility 

set^visibility specifies the default visibility attribute for subsequently created segments. 
This does not affect the visibility of existing segments or the currently open segment. 

set_visibility(visibility) 

int visibility; /* TRUE or FALSE */ 


6 .4-2. set_h igh 1 i ght ing 

set_highlighting specifies the default highlighting attribute for subsequently created seg¬ 
ments. 


set^higblighting(highlighting) 

int highlighting; /* TRUE or FALSE */ 
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6,4^,$. set:_detectability 

set_dotectability specifies the default detectability attribute for subsequently created seg¬ 
ments. 


set_detectabi1ity(detectabi1ity) 

int detectability; /* O thru 2^^—1 */ 


set_image_translate_2 

set_image_translate_2 sets the default image transformation attribute for subsequently 
created segments. 

set_image_translate_2(tx, ty) 

float tx, ty; /* x and y translation values in NDC */ 


The default image transformation is set to a two-dimensional translate by tx and ty. 


6 .4‘^‘ set_image_transformation_2 

set_image_transformation_2 sets the default image transformation for subsequently 
created segments. 

set_image_transformation_2(sx, sy, a, tx, ty) 
float sx, sy; /* x and y scale factors */ 

float a; /* rotation value in radians clockwise about z axis */ 

float tx, ty; /* x and y translation values in NDC */ 


The default transformation is set to a two-dimensional scale by »x and sy, rotation by a, and 
translation by tz and ty. The order of transformation is: 

1. Scale about the origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rotation of ir/2 radi¬ 
ans will rotate the x axis into the y axis. 

3. Translate. 

To scale and rotate about a point z, y, add dx to tz and add dy to ty, where 

dx = X — (x * sx * co«(a) — y * sy * sin (a)) 
dx = y — (x * sx * sin (a) + y * sy * cos (a)) 


6.4>S. set_image_translate_3 

set_image_translate_3 sets the default image transformation attribute, in normalized dev¬ 
ice coordinates, for subsequently created segments. 
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set_imago_translate_3 (tx, ty, tz) 

float tx, ty, tz; /* x, y, and z Translation Values in NDC */ 
The default image transformation is set to a three-dimensional translate by tz, ty, and tz. 


6.4- 7. set_image_trans formation_3 

set_image_transformation_3 sets the default image transformation attribute for subse¬ 
quently created segments. 

set_image_transforniation_3(sx, sy, sz, ax, ay, az, tx, ty, tz) 


float 

sx. 

sy. 

sz; 

/* 

X, y, and z Scale Factors */ 

float 

ax. 


az; 

/* Rotation Values in radians clockwise */ 
/* about the x, y, and z axes. */ 

float 

tx, 

ty. 

tz; 

/* 

X, y, and z Translation Values in NDC */ 


The default image transformation is set to a three-dimensional scale by tz, ty, tz, a three- 
dimensional rotation by ax, ay, az, and a three-dimensional translation by tx, ty, tz. The order of 
transformation is: 

1. Scale about (0.0, 0.0, 0.0) in NDC space, 

2. Rotate about (0.0, 0.0, 0.0) in NDC space, first about the z-axis, then about the y*axis, and 
then about the «-axis. Since NDC space is a left-handed coordinate system, rotations are 
computed using the left-hand rule. When the origin is viewed from the positive side of the 
axis of rotation, clockwise rotations correspond to positive rotations. 

3. Trantlate. 


6 .4-8. set_seginent_visibility 

set_segmer:t_visibility specifies the vitibility attribute for the named segment, 

set_seginent_visibi 1 ity (segment_name, visibi 1 ity) 
int segment_name; 

int visibility; /* TRUE or FALSE */ 

When vitibility is set to FALSE, the segment is erased from the view surfaces. The segment is 
redrawn again when visibility is set to TRUE. 


6.4-9. set_segment_highlighting 

set_segment:_highlighting specifies the highlighting attribute for the named segment. 

set_segment_hlghlighting (segment_naine, highlighting) 
int segment_name; 

int highlighting; /* TRUE or FALSE */ 
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When highlighting is set to TRUE, the segment is blinked once. 


6 , 4 ^ 10 , set_segment_detectability 

s©t_segment_det:ectability specifies the detectability dXinhutt for the named segment. 

set_seginent_detectability(segment_nazae, detectability) 
int seginent_name; 

int detectability; /* 0 thru 2 ”—1 */ 

When detectability is set to 0, the segment cannot be picked by the awaitjpick input function. If 
two segments overlap, the segment with the greatest detectability is picked. 


6.4-11- set_segment_image_translate_2 

set:_segmen-h_image_-translat:e_2 sets the image transformation attribute for the named 
segment. 

set_segment_image_translato_2(seginent_name, tx, ty) 
int s©gnient__naino; 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

The image transformation is set to a two-dimensional translate by tx^ ty. The named segment is 
erased from the view surface and then redrawn after the new image transformation is applied. 
This may be done while the segment is open. 


6.4>d2. set_segment_image_trans forination_2 

set_seginent_image_transformation_2 sets the image transformation attribute for the 
named segment. 


s©t_segment_image_transformation_2 (s©gm©nt_namo, sx, sy, a, tx, ty) 
int segment_namo; 

float sx; /* x Seal© Factor */ 

/* y Scale Factor */ 

Rotation Value in radians clockwise about z axis*/ 
X Translation Value in NDC */ 
y Translation Value in NDC */ 


float 

float 

float 

float 


sy; 

a; 

tx; 

ty; 


/* 

/* 

/* 


The image transformation is set to a two-dimensional scale by sz and ay, a two-dimensional rotar 
tion by o, and a two-dimensional translation by tx and ty. The order of transformation is: 

1. Seale about the origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rotation of ;r/2 radians 
will rotate the x axis into the y axis. 
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3. Translate. 

To scale and rotate about a point 2 , y, add dx to tx and add dy to ty, where 

(2*52*005(0)—y*«y*sin(o)) 

rf 2 =i/—(2*e2*sin(o)+y*5j(*cos(o)) 

The named segment is erased from the view surface and then redrawn after the new image 
transformation is applied. This may be done while the segment is open, 

6.4‘IS. set_segment_image_translate_3 

set_segment:_iiaage_translato_3 sets the image transformation attribute for the named 
segment. 

set_segment_image_translate_3(segment_name, tx, ty, tz) 
int segment_name; 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

float tz; /* z Translation Value in NDC */ 

The image transformation is set to a three-dimensional translate by tx^ ty, tz. The named seg¬ 
ment is erased from the view surface and then redrawn after the new image transformation is 
applied. This may be done while the segment is open. 

6.4>14‘ set_segment_image_trans forination_3 

set_segment_iiiiage_transformation_3 sets the image transformation attribute for the 
named segment. 

set_segment_image_transformation_3 (segment_naine, sx, sy, sz, ax, ay, az, tx, ty, tz 


int 

segment. 

.name, 

r 







float 

sx; 

/* 

x Scale Factor 

*/ 






float 

sy; 

/* 

y Scale Factor 

*/ 






float 

sz; 

/* 

z Scale Factor 

*/ 






float 

ax; 

/* 

Rotation Value 

in radians clockwise 

about 

the 

X 

axis 

*/ 

float 

ay; 

/* 

Rotation Value 

in radians clockwise 

about 

the 

y 

axis 

*/ 

float 

az; 

/* 

Rotation Value 

in radians clockwise 

about 

the 

z 

axis 

*/ 

float 

tx; 

/* 

X Translation Value in NDC */ 






float 

ty; 

/* 

y Translation Value in NDC */ 






float 

tz; 

/* 

z Translation Value in NDC */ 







The image transformation is set to a three-dimensional scale by sx, sy, sz, a three-dimensional 
rotation by ax, ay, az, and a three-dimensional translation by tx, ty, tz. The order of transformar 
tion is: 

1. Scale about (0.0, 0.0, 0.0) in NDC space. 
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2. Rotate about (0.0, 0.0, 0.0) in NDC space, first about the z*axis, then about the s^axis, and 
then about the xr-axis. Since NDC space is a left-handed coordinate system, rotations are 
computed using the left-hand rule. When the origin is viewed from the positive side of the 
axis of rotation, clockwise rotations correspond to positive rotations. 

3. Translate. 

The named segment is erased from the view surface and then redrawn after the new image 
transformation is applied. This may be done while the segment is open. 


6.5. Inquiring Retained Segment Dynamic Attributes 


The functions described below are for inquiring the settings of the dynamic attributes for 
retained segments. There are two classes of functions for inquiring retained segment dynamic 
attributes. One class obtains the default attributes for subsequently created segments and the 
other obtains attributes on a named segment basis. 

Errors which can be returned from these functions are: 

• There is no segment called segment_natne. 

• The default image transformation attribute value is of a more complex type than the 
inquiry function used. 

• The segment’s image^transformation^type attribute value is incompatible with the 
requested function. 

• The segment’s image^transformation^type attribute value is of a more complex type than 
the inquiry function used. 


6.5.1. inquire_visibility 

inquire_visibility obtains the default visibility attribute for subsequently created seg¬ 
ments. 


inquire_visibility (visibility) 

int ‘visibility; /* TRUE or FALSE */ 


6.5.2. inquire_highlighting 

inquire_highlighting obtains the default highlighting attribute for the subsequently 
created segments. 

inquire_bighlighting(highlighting) 

int ‘highlighting; /‘ TRUE or FALSE */ 
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6.5.S. inquire_detectability 

inquire_detectability obtains the default detectability attribute for the subsequently 
created segments. 

inquire_detectability (detectability) 

int ‘detectability; /* O thru 2^*—1 */ 


6 . 5 . 4 . inquire_image_translate_2 

inquire_image_translate_2 obtains the two-dimensional translation components of the 
default image transformation for subsequently created segments. 

inquire_image_translatG_2 (tx, ty) 

float *tx, *ty; /* x and y Translation Values in NDC */ 


6.5.5. inquire_iinage_transforination_2 

inquire_image_transformation_2 obtains the two-dimensional scale factor, rotation, and 
translation components of the default image transformation attribute for subsequently created 
segments. 

inquire_image_transformation_2 (sx, sy, a, tx, ty) 

float *sx, *sy; /* x and y Scale Factors */ 

float *a; /* Rotation Value in radians clockwise about the z axis*/ 

float *tx, *ty; /* x and y Translation Values in NDC */ 


6.5.6. inquire_image_translate_3 

inquire_image_transla-te_3 obtains the three-dimensional translation components of the 
default image transformation attribute for subsequently created segments. 

inquire_imago_translate_3(tx, ty, tz) 

float *tx, *ty, *tz; /* x, y, and z Translation Values in NDC */ 


6.5.7. inquire_iinage_transforination_3 

inquire_image_transformat:ion_3 obtains the three-dimensional scale factor, rotation, 
and translation components of the default image transformation attribute for subsequently 
created segments. 
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inquiro_image_transformation_3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
float *sx, *sy, *sz; /* x, y, and z Scale Factors */ 

float *ax, *ay, *az; /* Rotation Values in radians clockwise about the 

/* X, y, and z axes */ 

float *tx, *ty, *tz; /* x, y, and z Translation Values in NE>C */ 



V 


6.5.8. inquire_segmerit_visibility 

inquire_segment_visibility obtains the rwi6i7i7y attribute for the named segment. 

inquire_segment_visibility (segment_name, visibility) 
int segment_name; 

int ‘visibility; /* TRUE or FALSE */ 


6.5.9. inquire_segment_highlighting 

inquire_segTiient..highlighting obtains the highlighting attribute for the named segment. 

inquire_seginent_highlighting(segment_name, highlighting) 
int segment_name; 

int ‘highlighting; /* TRUE or FALSE */ 



6.5.10. inquire_seginent_detectability 

inquire_segment_detectability obtains the detectability attribute for the named seg¬ 
ment. 

inquire_segment_detectability(segment_name, detectability) 
int segment^name; 

int ‘detectability; /‘ 0 thru 2*^—1 ‘/ 


6.5.11. inquire_segment_image_translate_2 

incpaire_segment_image_translate_2 obtains the two-dimensional translation com¬ 
ponents of the named segment’s image transformation attribute. 

lnqulre_segmGnt_imag©_translat©_2(segment^name, tx, ty) 
int segment^name; 

float *tx; /* x Translation Value in NDC */ 

float *ty; /* y Translation Value in NDC ‘/ 
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6.5.12. inquire_seginen't_image_t:ransformatlon_2 


inquire_segment_iiaage_t:ransformat:ion_2 obtains the two-dimensional scale factor, 
rotation, and translation components of the named segment’s image transformation attribute. 


inquir©_segment_image_transformation_2 (s©gmont_nain0, sx, sy, a, tx, ty) 
int segm©nt_nam©; 

X Seal© Factor */ 
y Scale Factor */ 

Rotation Value in radians clockwise about the 2 axis*/ 
X Translation Value in NDC */ 
y Translation Value in NDC */ 


float 

float 

float 

float 

float 


*sx; 

*sy; 

*a; 

*tx; 

*ty; 


/* 

/* 

/* 

/* 

/* 


6.5.1$. inquire_seginent_iinage_translate_3 

inqiJiire^segment__image_trans 1 ate_3 obtains the three-dimensional translation com¬ 
ponents of the named segment’s image transformation attribute. 

inqulr©_seginent_imag©_translate_3 (segment_namo, tx, ty, tz) 
int segment_nam©; 

float *tx; /* X Translation Value in NDC */ 

float *ty; /* Y Translation Value in NDC */ 

float *tz; /* z Translation Value in NDC */ 


6 . 5 . 14 . inquire_segment_iinage_transformation_3 

inqiiire_segiD©nt_iinage_trans formation__ 3 obtains the three-dimensional scale factor, 
rotation, and translation components of the named segment’s image transformation attribute. 

inquir©_segment_imag©_transformation_3(segment_name, sx, sy, sz, 

ax, ay, az, tx, ty, tz) 


int segment. 

_nam©; 








float 

*sx; 

/* 

X Scale Factor 

V 






float 

*sy; 

/* 

y Scale Factor 

V 






float 

*sz; 

/* 

z Scale Factor 

V 






float 

*ax; 

/* 

Rotation Value 

in radians clockwise 

about 

the 

X 

axis 

V 

float 

*ay; 

/* 

Rotation Value 

in radians clockwise 

about 

the 

y 

axis 

V 

float 

*az; 

/* 

Rotation Value 

in radians clockwise 

about 

the 

z 

axis 

V 

float 

*tx; 

/* 

X Translation Value in NDC */ 






float 

*ty; 

/* 

y Translation Value in NDC */ 






float 

*tz; 

/* 

2 Translation Value in NDC */ 
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Chapter 7 


Input Primitives 


SunCore supports several logical input devices providing for interactive use of the graphics sys¬ 
tem. The physical input devices provided are the keyboard and the mouse. The mouse is versar 
tile in that it can be used both as a pointer and a button device. 

In the terminology of the ACM Core specification, input devices fall into two distinct classes, 
namely: devices that generate events, and devices that may only be sampled for position or 
numerical values. SunCore supports the ACM Core standard level 2 input (synchronous); hence 
no event generation or event queue is supported. The supported logical devices in SunCore are: 


Table 7-1: Input Devices Supported By SunCore 



Pick identifies (picks out) a segment or a primitive within a segment. SunCore uses 

the mouse as a pick device. 

Keyboard provides alphanumeric information to the application program. 

Button provides a means of choosing among several alternatives. In SunCore, the three 
button devices are on the mouse. 

Stroke generates a sequence of positions in normalized device coordinates. In SunCore, 
the stroke device is the mouse. 

Locator provides a position in normalized device coordinates. SunCore uses the mouse as 
the locator device. 

Valuator provides a scalar value to the application program which samples it. SunCore 
uses the mouse as the valuator device. 

A logical input device must be initialized before it can be used. 

7.1. Initializing and Terminating Input Devices 
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7 .1.1. initialize_device — Initialize a Specific Device 

initialize^device initializes a specific logical device. This routine must be called before 
accessing any of the input devices. 

initialize_device (device_class, device_nuinber) 

int device_class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int devico_number; /* There are: */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/* 1 LOCATOR device */ 

/* 1 VALUATOR device */ 

An initialized input device which uses position information from the mouse must be associated 
with an initialized view surface (as an echo surface) before valid data can be read from the dev¬ 
ice. See appendix B for details. 

Errors returned from initializo_device: 

• The device specified by device^number is not initialized. 

• The device specified by device_nttmber is already initialized. 

Note: that if the KEYBOARD device is initialized and the program crashes before the KEY¬ 
BOARD device is terminated, the tty will not echo and cbreak will be set. To recover from 
this condition, type ‘reset’ followed by a carriage return. 

7.1.2. t;erininat:e_device — Disable a Specific Devtce 
•terminat:e_device disables a specific device. 

terminate_device (device_class, device_nuinber) 

int devico^class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device^number; /* There are: */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/* 1 LOCATOR device */ 

/* 1 VALUATOR device */ 


Errors returned from terminate_device: 

• The device specified by device^number is not enabled. 
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7.2* Device Echoing 

Device echoing means that SunCore can provide a visible indication to the user that the system 
has seen the input from a specific input device. 

SunCore provides the means whereby the application programmer can control the way in which 
input devices are echoed to the user of the graphics system. 

Firstly, the types of echoing for each device are defined here. The tables below describe the 
types of echoing for specific devices. 

Table 7-2: Echoing for Pick Device 



Pick Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

SunCore blinks the picked segment briefly. A printer’s fist (pointing finger) 
indicates the position of the pick device. 

2 

A printer’s fist (pointing finger) indicates the position of the pick device. Sun¬ 
Core does not blink the picked segment. 


o 


Table 7-3: Echoing for Keyboard Device 



Keyboard Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

The string which the user typed at the keyboard is echoed on the screen start¬ 
ing at the echo reference position. 


o 
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Table 7-4: Echoing for Button Device 




Button Device 

Echo Type 


Actions Performed 

0 

No echo 


1 

No echo 



Table 7-5: Echoing for Stroke Device 


Echo Type 

Stroke Device 

Actions Performed 

0 

No echo 

1 

a printers fist (pointing finger) sign is displayed at the cursor position. 

2 

A string of dots is drawn to follow the path of the cursor, (not implemented) 

3 

A solid line is drawn to follow the path of the cursor, (not implemented) 

4 

a printers fist sign is displayed at the final position of the cursor, (not imple¬ 
mented) 



o 
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Table 7-6: Echoing for Locator Device 


Echo Type 

Locator Device 

Actions Performed 

0 

No echo 

1 

A printers fist (pointing finger) sign is displayed at the position of the locator. 

2 

A solid line is drawn connecting the echo reference point with the locator. 

3 

A solid line is drawn connecting the echo reference point with the x coordinate 
of the locator. 

4 

A solid line is drawn connecting the echo reference point with the y coordinate 
of the locator. 

5 

A solid line is drawn connecting the echo reference point with either the x coor¬ 
dinate, or the y coordinate, of the locator, whichever is farthest from the echo 
reference point. 

6 

A box is drawn with the position of the locator as one corner, and the echo 
reference point as the opposite corner. 


Table 7-7: Echoing for Valuator Device 


Echo Type 

Valuator Device 

Actions Performed 


0 

No echo 


1 

The current value of the valuator is displayed on the 
echo reference point. 

screen starting at the 

2-11 

SunCore does not perform the actions as described in the ACM Core 
specification, which sets the values of the valuator into various parameters of 
the imaytJLtamlormaiionJtypt attribute of retained segments. SunCore 
leaves this up to the application program. 
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7.2.1. set^echo — Define Type of Echo for Device 


set_echo (devico^class, devic©_niimb©r, ©cho_typo) 

int devico_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int devic©_number; 
int echo_type; 


7.2.2. set_echo_group — Define Type of Echo for a Group of Devices 


set_echo_group (d©vice_class, device_nuinber_array, n, echo_type) 
int device.class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_nuinber_array []; 

int n; /* number of devices in array */ 

int echo_type; 


7.2.3. set_echo_position — Define Echo Reference Point 

set_echo_position specifies the position, in normalized device coordinates, which will be 
used as the echo reference point. The coordinates must lie within the bounds of NDC space, or 
set_echo_position will set the echo reference point to be the point in NDC space closest to the 
specified point. 

set_echo_position(device_class, d©vic©_nuiDber, echo_x, echo_y) 
int devico_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int devico_number; 

float echo_x; /* x Coordinate of Echo Point */ 

float echo_y; /* y Coordinate of Echo Point */ 

The echo reference point that this function defines is used for certain types of echo such as 
rubber band locator echo. 


7 . 2 . 4 . set_echo_sur face — Define View Surface for Echo 
s©t_ocho_sur face specifies the viewing surface on which echoing will be done. 


set_echo_surface(devic©_class, device_numbor, surface_name) 
int device.class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int devico_number; 

struct vwsurf *surfaco_namo; /* See appendix B */ 
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An initialized input device which uses position information from the mouse must be associated 
with an initialized view surface (as an echo surface) before valid data can be read from the dev¬ 
ice. See appendix B for details. If a NULL pointer is given for the surfacc^name argument, any 
association of the specified input device with an echo surface is ended. 


7*3* Setting Input Device Parameters 


7.3.1. set_locator_2 —Initialize Locator Position 

set_locator_2 sets the initial locator position in normalized device coordinates. 

set_locator„2(locator_number* x, y) 
int locator_nuinber; 
float x; 
float y; 


StinCore currently does not use this initial position of the locator. 


7.3.2. set^valuator — Initialize Value and Range for Valuator Device 
set_valuator sets the value and range for the valuator device. 

set_valuator (valuator_nuinber, inltial_valuo, low, high) 
int valuator_nuinber; 
float initlal_valuo; 
float low; 
float high; 


The default values are: initiaLvalue = 0.0, low = 0.0, and high =1.0. 


7.3.3. set_keyboard — Initialize Keyboard Parameters 

set_keyboard sets the size of the character buffer for the keyboard, the initial character 
string, and the initial character cursor counting from the echo reference position. 

set_keyboard(keyboard^number, buffer_sizo, initial_string, initial_cursor_position) 
int keyboard_number; 
int buffer_size; 
char *initial_string; 
int initial_cursor_position; 

SunCore uses default values of buffer^size =» 80, initiaLstring = **enter:”, and 
initiaLcursor^position = 7. The maximum buffer^ize and the maximum length of initial_string 
are 80 characters. 
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set_stroke — Initialize Stroke Device 
set_st:roke sets parameters for the stroke device. 

set_stroke(stroke_number, buffer_sizG, distance^ time) 
int stroke_n\iinber; /* Device Number */ 

int buffer_size; /* Number of x, y points - not used */ 
float distance; /* Minimum distance to move */ 
int time; /* Not used */ 

The buffer_8ize argument is the maximum number of x, y points in a stroke. The distance argu¬ 
ment is the minimum distance, in normalized device coordinates, which the mouse must move 
before a new point is added to the x, y list comprising the stroke. The default setting is dis- 
tance=0.01. 


7.3.5. set_pick — Initialize Pick Device 

set_pick sets the aperture for the pick device. 

set_pick(pick-number, aperture) 

int pick-number; /* Device Number */ 
float aperture; /* Device aperture */ 

The aperture argument provides control over the ‘sensitivity’ of the pick device. A square is 
defined with its center at the cursor position and with sides of length 2 * aperture. Segments 
that intersect this square can be picked, aperture is given in normalized device coordinates. An 
error is returned if the pick-number is incorrect or if the aperture <0.0. The default aperture 
square has two pixels per side. 


7.4. Reading From Input Devices 


7.4 I- await_any_button — Wait for Mouse Button 

await_any_but'ton waits for the user to click any of the mouse buttons. 

await_any_button(time, button_number) 

int time; /* Time in microseconds to wait */ 

int *button_number; /* Button which was hit */ 

await:_any_button waits for the user to click any initialized button on the mouse, or until the 

time specified by the time parameter expires. If the fime argument is exactly zero, the buttons 

are checked once, then the function returns to the caller immediately. 

If a button is clicked before time expires, the number of the button is returned in the 
button^number parameter. If the user does not click any mouse button before time expires, the 
function returns a button number of zero. 
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For the mouse, button numbers 1, 2, and 3 represent the left, middle, and right buttons, respec¬ 
tively, when the buttons are facing away from the user. 


7.^.2. await_pick — Wait for Pick Device 

await_pick waits for the user to pick an output primitive within a visible and detectable 
retained segment. 

await_pick(time, pick_nuiiiber, segiiient_name, pick_id) 

int time; /* Time in microseconds to wait */ 

int pick_number; 
int * segment_name; 
int *pick_id; 


await_pick waits for the user to click the left hand button on the mouse, or until the time 
specified by the time parameter expires. If the time argument is exactly zero, the function tests 
the button once, and if the button has been clicked, performs the pick operation. 

If the button is clicked before time expires, the function returns the segment„name of the seg¬ 
ment that the pick device is pointing at, and the pick_id parameter is set to the value of the 
pick^id attribute of the primitive that was picked. If the user does not click any mouse button 
before time expires, or no segment is found where the user points, the function sets the 
segment_name and pick^id parameters to zero. 

await^pick only searches those segments which are visible and detectable and appear on the 
echo surface of the specified PICK device. Primitives within a segment have bounded volume 
descriptors. The square pick aperture must intersect one of these ‘extents’ in order that the 
segment^name and pick^id be returned. If more than one segment is at the point, the segment 
with the highest value of the detectability attribute is returned. Detectability may be set to zero 
to prevent a segment from being picked. 


Errors returned from await_pick: 

• The specified pick device does not exist. 


7.4-S. await_keyboard — Wait for Input from the Keyboard 
await_keyboard waits for the user to type a line of input on the keyboard. 

await_keybcard(time^ keyboard_number, input_string, length) 
int time; /* Time in microseconds to wait */ 

int keyboard_numbor; 
char *input_string; 
int *length; 


await_keyboard waits for the user to enter data at the keyboard, or until the time specified 
by the time parameter expires. If the time argument is exactly zero, the function tests once to 
see if a character has been typed, and then returns to the caller. 
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If any data is entered at the keyboard before time expires, the function returns the typed char¬ 
acters in an array pointed to by input^etring. The length of this character string is returned in 
length. The string is null terminated. If the user does not enter any data before time expires, 
the function sets the length parameter to zero. If a carriage-return or newline character is 
typed, the function returns with the input string containing a newline character as the last non¬ 
null character. 


Errors returned from await_keyboard: 

• The specified keyboard does not exist. 


7.4.4. await_stroke _2 — Wait for User to Draw a Line 

await:_st:roke_2 waits for the user to draw a line, consisting of a list of points in normalized 
device coordinate space, using the mouse. 

await_stroke_2(time, stroke_nuinber, array^sizo, x_array, y_array, number_points) 
int time; /* Time in microseconds to wait */ 

int stroke_number; /* Stroke device to wait for */ 

int array_sizo; /* Maximum size of x and y arrays */ 

float x_array[]; 
float y_array[]; 

int ‘number.points; /* Number of x, y coordinates actually read */ 


awaitj_stroke waits for the user to draw a line using the mouse, or until the time specified by 
the time parameter expires. If the time argument is exactly zero, the function tests once to see 
if a line has been drawn, and then returns to the caller. 

The line starts at the current position of the locator, and finishes when the user clicks button 3 
on the mouse. When the function returns, the number of x, y coordinates actually read is 
returned in the number^points argument. When the number of points read equals array^size the 
function returns before time expires. 


7.4.5. await_any_button_get_locator _2 — Read Locator When Button Clicked 

await.any_button_get_loca'tor_2 waits for the user to click any of the mouse buttons. 
When the button is clicked, the function returns the current normalized device coordinates of 
the locator. 


await_any_button.get_locator_2(time, locator_number, button_number, x, y) 
int time; /* Time in microseconds to wait */ 

int locator.number; /* Locator device to wait for */ 

int *button.number; /* Button which was clicked */ 

float *x, *y; /* Returned point in NDC */ 

awa it.any.button.get.locator_2 waits for the user to click any mouse button, or until 
the time specified by the time argument expires. If the time argument is exactly zero, the func¬ 
tion checks if any buttons have been clicked immediately and then returns. 
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If the time expires before the user has clicked any of the mouse buttons, the function returns a 
zero in the button^number argument. 


7.4.6. await:_any_button_get_valuator —Read Valuator When Button Clicked 

await:_any_but:ton_ge't_valuat:or waits for the user to click any of the mouse buttons, or 
for a specified time. When the button is clicked, the function returns the current value of the 
valuator. 

awalt_any_button_get_valuator(time, valuator_numbGr, button^number, value) 
int time; /* Time in microseconds to wait */ 

int valuator_numbGr; /* Valuator n umb er to read from */ 

int *button_number; /* Button which was clicked */ 

float *value; /* Value of valuator */ 

await_any_button_get_valuator waits for the user to click any mouse button, or until 
the time specified by the ftmc argument expires. If the time argument is exactly zero, the func¬ 
tion checks if any buttons have been clicked and then returns immediately. 

If the user clicks one of the mouse buttons, the function returns with the value of the valuator, 
and the number of the button which was clicked. If the time expires before the user has clicked 
any of the mouse buttons, the function returns a zero in the button_number argument. Move¬ 
ment of the mouse left or right lowers or raises the value of the valuator. 


7.4.7. get_inouse_state — Low Level Mouse Support (SunCore extension) 

get_mbuse_state reads the low level mouse x, y, and button information corresponding to a 
particular input device. The buttons are up-down encoded, and the location of the mouse is in 
normalized device coordinates. 

get_mouse_state(device_class, devicG_number, x, y, buttons) 
int device_class; /* PICK, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; 
float *x, *y; 
int ‘buttons; 

of buttons is the right-hand mouse button, 
of buttons is the middle mouse button, 
of buttons is the left-hand mouse button, 
bit means that the button is tip, while a one bit means that the button is down. 


Bit 0 
Bit 1 
Bit 2 
A zero 


7.5. Inquiring Input Status Parameters 
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7 , 5 . L inquire_echo — Obtain Type of Echo for Device 
inquire_echo obtains the echo_type for the specified device. 


inquire_echo(device_class, dovico_number, echo_type) 

int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int devico_n\unbor; 
int *echo_typG; 


7 . 5 . 2 . inquire_echo_position — Obtain Echo Reference Point 


inquire_echo_position obtains the position, in normalized device coordinates, of the echo 
reference point for the specified device. 

inquire_echo_position{dGvice_class, device^number, echo_x, echo_y) 
int devicG^class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device__nun)ber; 

float *Gcho_x; /* x Coordinate of Echo Point */ 

float *echo_y; /* y Coordinate of Echo Point */ 


7 . 5 . 3 . inquire_echo_surface — Obtain View Surface for Echo 

inquire_echo_surface obtains the viewing surface on which echoing is done for the 
specified device. 

inquire_echo_surface (device_class, device_nuinber, sur facG_name) 
int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int devicG_nuinber; 

struct vwsurf *surface„name; 


7.5.4. inquire_locator_2 — Obtain Initial Locator Position 

inquire_locator_2 obtains the initial position of the specified locator in normalized device 
coordinates. 

inquirG_locator_2(locator_numbGr, x, y) 
int 1 o cat or_nuinber; 
float *x; 
float *y; 
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7.5.5. inquire_valuator — Obtain Value and Range for Valuator Device 

inquire_valuator obtains the value and range for the specified valuator device. 

inquire_valuator(valuator_number, inltial_value, low, high) 
int valuator_nuiiiber; 
float: *init:ial_valuo; 

float *low; 
float *high; 


7.5.5. inquire_keyboard — Obtain Keyboard Parameters 

inquire_keyboard obtains the size of the character buffer, the initial character string, and 
the initial character cursor for the specified keyboard. 

inquire_keyboard(keyboard_nuinber, buffer_sizo, initial_string, 
initial_cursor_position) 
int keyboard_number; 
int *bu f fer_size; 
char *initial_string; 
int *initial_cursor_position; 


7.5.7. inquire_stroke — Obtain Stroke Device Parameters 

inquire_stroke obtains the buffer size, distance, and time parameters for the specified stroke 
device. 


inquire_stroke(stroke_nuinber, buffer_size, distance, time) 


int 

stroke_number; 

/* 

device 

number */ 

int 

*buffer_size; 

/* 

number 

of X, y points in buffer - not used* 

float 

♦distance; 

/* 

minimum 

distance to move in NDC */ 

int 

♦time; 

/* Not used 

V 


/ 
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Chapter 8 


Programming Examples 


8.1. The Sun Workstation Factory 

This example provides a relatively simple programming example that nevertheless uses a goodly 
number of SunCore’s facilities. The example is called factory. It has a factory building with a 
smokestack and a cloud of smoke puffing out. Silicon chips move in at one end of the building, 
and Sun Workstations come out of the other end. 

Facilities displayed by this simple example include texturing, translation, scaling, and output 
clipping. The example is presented in pieces, with a narrative accompanying each of the pieces. 


8.1.1. Declarations and the Main Program 

First there is an include of the file usercore.h which contains the definitions requirerf for using 
the graphics package: 

#lnclude <usercore.h> 

Then there are some definitions: 


/* Define segment numbers */ 

#define FACTORY 10 
#define CLOUD 9 
#define WORKSTATION^.! 1 

#define W0RKSTATI0N_2 2 

tdefine W0RKSTATI0N_3 3 

#define CHIP_1 4 
#define CHIP_2 5 
#define CHIP_3 6 

Then we define and initialize the variables that describe the outlines of the various objects in the 
picture: 
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static float delta[] = <0.0, 0.025, 2*0.025, 3*0.025, 4*0.025, 

5*0.025, 6*0.025, 7*0.025, 8*0.025, 9*0.025, 
10*0.025, 11*0.025, 12*0.025}; 

static float redtex[] = <0.9961, 0.1765, 0.1334, 0.1334, 0.4667, 

0.1334, 0.1334, 0.1334, 0.8001, 0.2667, 

0.5334, 0.0>; 

static float grntex[] = <0.5334, 0.2079, 0.5334, 0.5334, 0.5334, 

0.5020, 0.5020, 0.3334, 0.2667, 0.5334, 

0.5334, 0.2667}; 

static float blutex[] = <0.0, 0.0, 0.4001, 0.0, 0.2118, 0.3529, 

0.6471, 0.4001, 0.4001, 0.4001, 0.4001, 0.3882} 

int bw2dd(); /* Device driver name for the Sun-2 */ 

/* monochrome display — see appendix B */ 
struct vwsurf vsurf = DEFAULT_VWSURF(bw2dd); 

/* The DEFAULT_VWSURF macro is defined */ 

/* in usercore.h */ 

Then we have the main program’. 
main () 

i 

short i, pO, pi, p2, p3; 
int error; 
float scale; 
float clx, cly; 


The first call in the program is to initialize SunCore, with an appropriate exit if there is an 
error returned: 

error = initialize_core(DYNAMICB, NOINPUT, TWOD); 
if (error) 
exit(0); 


Then we initialize and select a view surface. Again, we exit if there was an error returned: 

error = initialize_view_surface(fivsurf, FALSE); 
error 1= select_view_surface(&vsurf); 
if (error) 
exit (1); 

Then we establish a viewport and a window. Note that we can set clipping on output — this t« a 
SunCore extension to the A CM Core. 

set_viewport_2(0.05, 0.95, 0.05, 0.7); 
sot_window(30.0, 225.0, 30.0, 225.0); 
set__output_clipping (TRUE) ; 
set_window_clipping (FALSE) ; 
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Set up the color lookup table, 

defino_color_indicos(fivsurf, 1, 12 , redtex, grntex, blutex); 



Now make a temporary segment for a title and border, 

creato_ten53orary_segment 0 ; 
movo_abs_2(30., 30.); 
line_rel_2(0., 195.); 
line_rel_2(195., O.); 
line_rel_2(O., -195.); 
line_rel_2(-195., O.); 
set_charprecision(CHARACTER); 
set_charsize(14 ., 14.); 
set_text_index(1) ; 
move_abs_2(40., 200.); 
text C’SunCore”); 
close_tenporary_segment () ; 


Next we establish a segment for the factory. This segment is the simplest type, since we perform 
no transformations of any kind on it, 

set_imago_transformation_type (NONE) ; 
create_retained_segment(FACTORY); 
factory(110.0, 60.0); 
closo_retained_segment(); 


Next we establish a segment for the cloud above the factory. This segment is subject to scaling, 
so we must allow for transformations. 

set_image_trans formation_type (XF0RM2) ; 
create_rGtained_segment(CLOUD); 
map_world_to_ndc_2(120., 100., &clx, &cly); 
set_segment_image_transformation_2 (CLOUD, 0.05, 0.1, 

0.0, clx, cly + 0.02); 
cloud(0., 0.); 
close_retainGd_segment(); 


Lastly, we establish segments for the chips and the workstations. The chips and workstations will 
be moving across the picture, so these segments must allow translation. 


o 
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set__image_trans formation_typo (XIiATE2) ; 

/* Do the Sun Workstation Segment */ 
create_retained_segment(WORKSTATION^!); 
sunws(160.0, 60.0); 
close_retained_segment0; 
creato_retained_segment(WORKSTATION_2) ; 
sunws(160.0, 60.0); 
close_retained_segment(); 

create_retained_segmont(W0RKSTATI0N_3); 
sunws(160.0, 60.0); 
closo„retained_segment0; 

/* Do the Chip Segment */ 
create_retained_segment(CHIP_1); 
chip(20.0, 70.0); 
close_retained_segment0; 
create_retained_segment(CHIP_2); 
chip(20.0, 70.0); 
close_retained_segment() ; 
create_retained_segment(CHIP_3); 
chip(20.0, 70.0); 
close_retained_segment0; 


Notice that we created the workstation all on top of each others and also all the chips on top of 
each other. The actual spatial separation of the individual segments is handled tn the mam body 
of the animation code. 

Now we get to the body of the code which animates the picture. The outer for loop is done 100 
times. The calls on the translation routines make the chips and workstations move. The inner 
for loop makes the cloud grow. 


pO = O; pi = 4; p2 = 8; 
for (i=0; KlOO; i++) { 

set_segment_image_translate_2(WORKSTATION^!, delta[pO], 0.0); 
set_segment_image_translate_2(W0RKSTATI0N_2, delta[pi], 0.0); 
set_segment_image_translate_2(W0RKSTATI0N_3, delta[p2], 0.0); 
set_segment_image_translate_2(CHIP_3, delta[p2], 0.0); 
set_segment_lmage_„translate_2 (CHIP_2, delta[pl] , 0.0) ; 
set_segment_image_translate_2(CHIP_1, delta[pO], 0.0); 
pO++; pl++; p2++; 

if (pO > 11) 
pO = O; 
if (pi > 11) 
pi = O; 
if (p2 > 11) 
p2 = O; 

for (scale=0.1; scale<1.0; scale += 0.2) 

set_segment_image_transformation^2(CLOUD, 0.5 * scale, scale, 
0.0, clx, cly + scale * 0.2); 


> 


Finally, when everything is done, we deselect the view surface, and terminate SunCore: 


&-4 
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deselGct_view_surfaco(fivsurf); 
terminate^coro(); 

). /* End of the main progpram */ 

The remainder of the demonstration program consists of the subroutines which fill in the details 
in the individual segments. 


8.1.2. The factory Drawing Function 

Firstf here are the coordinates for the outline of the factory itself. 

static float factdx[3 = -{0.0, 0.0, 8.0, 2.0, 3.0, 2.0, 3.0, 

1.0, 3.0, 1.0, 17.0, 0.0, -40.0}; 
static float factdy[] = {0.0, 20.0, 0.0, 20.0, 0.0, -20.0, 

0.0, 15.0, 0.0, -15.0, 0.0, -20.0, 0.0>; 

The next set of declarations describe the outline of the windows in the factory. 

static float winddx[] = {0.0, 0.0, 10.0, 0.0, —10.0}; 
static float winddy[] == {0.0, 5.0, 0.0, —5.0, 0.0}; 
static Int black = 3; 
static int brick ~ 1; 

Now we have the actual code of the factory drawing routine itself 

factory(xO, yO) 
float xO, yO; 

{ 

The xO and yO arguments to the factory function describe the absolute position in world coordi^ 

nates at which the factory should appear. The actual outline of the factory is described by the 

array of coordinates declared above. 

set_fill_indGX (brick); 

inovo_abs_2(xO, yO); /* Move to appropriate position */ 

polygon_rel_2(factdx, factdy, 12); /* Draw the factory outline */ 

Now we draw the windows within the factory. 

set_fill_index(black) ; 

move_rel_2(5.0, 10.0); /* Move to position of first window */ 

polygon_rel_2(winddx, winddy, 4); /* and draw the window */ 

movo_rel_2(15.0, 0.0); /* Move to position of second window */ 

polygon__rel__2 (winddx, winddy, 4); /* and draw the window */ 

set_fill_indGX(1); /* reset fill index */ 

} /* End of the factory drawing function */ 
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The next function is the one 


which draws the Sun Workstations within the workstation segment. 


8A.8. The Workstation Drawing Function 

The declarations below describe the outline of the Sun Workstation. Tube describes the screen, 
Case describes the outer outline of the case, base describes the base of the Workstation, and 
keybd describes the appearance of the keyboard: 

static float tubex[] = {0.0, 5.0, 0.0, —5.0}; 

static float tubey[] = {5.0, 0.0, —5.0, 0.0}; 

static float cas©x[] = {1.0, 7.0, 1.0, 1.0, —1.0, —7.0, —1.0}; 

static float casey[] = {7.0, 0.0, —7.0, 1.0, 7.0, 0.0, —1.0}; 

static float basex[] = {9.0, —1.0, —1.0, —5.0, —1.0}; 
static float basey[] = {0.0, 0.0, —2.0, 0.0, 2.0}; 

static float keybdx[] = {0.0, 10.0, 3.0, 0.0, -10.0, -3.0, 10.0, 3.0}; 
static float keybdy[] ~ {-1.0, 0.0, 2.0, 2.0, 0.0, -3.0, 0.0, 3.0}; 

sunws(xO, yO) 
float xO, yO; 

< 


Then all we have to do is move to the coordinates that were supplied as function arguments, and 
draw the lines: 


move_abs_2(xO+5.0, yO+8.0); 

polyline_rel_2(tubex, tubey, 4); 

move_rel_2(—2.0, —1.0); 
polyllne_rel_2(casex, casey, 7); 

movo_r©l_2 (—1.0, —7.0) ; 
polyline_rel_2(basex, basey, 5); 


/* Move to the position given */ 
/* Draw the tube */ 

/* Draw the case */ 

/* Draw the base */ 


mov©_abs_2(xO, yO+1.0); 

polyline_rel_2(keybdx, keybdy, 8); /* Draw the keyboard */ 

} /* End of the Workstation Drawing Function */ 


8 . 1 . 4 ^ The Chip Drawing Function 

The declarations below describe the outline of the chips. Plasti describes the outline of the chip 
itself, while lead describes the outline of the leads on the chip: 
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static float plastix[] = -(0.0, 16.0, 0,0, —16.0}; 

static float plastiy[] = -{4.0, 0.0, -'4.0, O.O}-; 

static float leadx[] = -(—1,0, 2.0, —1.0, 0.0}; 

static float leady[] = {2.0, 0.0, —2.0, —4.0}; 

chip(x0, yO) 
float xO, yO; 

{ 

short i; 

Then all we have to do is move to the coordinates that were supplied as function arguments^ and 
draw the lines: 

set_rasterop(XORROP); 

movo_abs_2(xO, yO); /* Move to appropriate position */ 

polyline_rel_2(plastix, plastiy, 4); /* Draw the chip */ 

move_rel_2(2.0, 1.0); 

for (i=0; i<5; i++) { /* Draw the leads on the chip */ 

polyline_rel_2(leadx, loady, 4); 
move_re1_2(3,0, 4.0); 

> 

set^rasterop (NORMAL); /* reset rasterop */ 

} /* End of the chip drawing function */ 


8.1,5. The Cloud Drawing Function 

The last function is the one that draws the cloud. The cloud function is easy: all we have to do 
is draw its outline. The actual scaling of the cloud is done in the main program. 


The declarations below describe the outline of the cloud: 

static float cloudxfj] - {0.0, 8.0, -8.0, -4.0, 2.0, 14.0, 8.0, 0.0, 

12.0, 8.0, 4.0, 0.0, -10.0, 10.0, 4.0, -2.0, 

- 6 . 0 , - 12 . 0 , - 6 . 0 , - 12 . 0 , - 10 . 0 }; 

static float cloudy[i] = {12.0, 8.0, 2.0, 6.0, 6.0, 10.0, ->4.0, -6.0, 

10.q, o n., -4.0, -10.0, -lo.o, -2.0, -6.0, 
-8.0, -4.0, 0.0, 4.0, -8.0, 4.0}; 


cloud(xO, yO) 
float xO, yO; 
{ 


Then all we have to do is move to the coordinates that were supplied as function arguments, and 
draw the lines: 
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move_abs_2(xO, yO); 

polylino_rol_2(cloudx, cloudy, 21); 

/* End of the cloud drawing function */ 
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Appendix A 



Deviations from ACM SIGGRAPH Core 


This appendix points out specific differences between the SunCore graphics package and the 
ACM SIGGRAPH Core Specification. In addition to differences noted here, SunCore has 
numerous extensions to the ACM Core which are documented in the main body of this manual. 

A.l. Unimplemented Functions 

Here is a list of those functions which SunCore does not implement: 

Table A-1: Unimplemented Primitive Attribute Functions 


o 


• set^charjuBt 


Primitive Attribute Functions 


• inquir eschar just 


Table A-2: Unimplemented Synchronous Input Functions 



Synchronous Input Functions 

• 

• 

inittaliz€_gr oup 
await^otroke_3 

• 

terminate^group 

• 

$et_echo_»egment 

• 

aet^pick 

• 

set^button 

• 

B€t_alUbnUon8 

• 

set_locator^S 

• 

BetJlocport^B 

• 

»et_locport^3 

• 

inquire^inp ut^capab iUtiea 

• 

mquire^input_device_ckaracteri3tica 

• 

inqwre^8troke_dimension 

• 

inquire^locator^dimension 

• 

inquire_pick 

• 

inquire^biitton 

• 

inquire^loe ato r^3 

• 

• 

inquire^lo cport_2 
inquire^echo^segmenta 

• 

«ir c_/o cp ort^3 



Revision F of 15 May 1985 


A-1 








Deviations from ACM SIGGRAPH Core 


SunCore Reference Manual 


Table A-3: Unimplemented Asynchronous Input Functions 


Asynchronous Input Functions 

• 

enable^device 

• enable^group 

• 

disable_device 

• disable_group 

• 

didable_all 

• read_locator_B 

• 

read^locator_S 

• read^valuator 

• 

await_event 

• Jlush_device_events 

• 

flttsk^group_event9 

• fivsk^alLevents 

• 

associate 

• disassociate 

• 

disassociate_device 

• disassociate^group 

• 

disassociate_aU 

• get^pick^data 

• 

get_keyboard_data 

• get^stroke^data^B 

• 

get_stroke_data^S 

• get_locator^data_8 

• 

get_locator_data^S 

• get_valuator_data 

• 

inquire_device^associations 

• inqmre_devic€_status 


Table A-4: Unimplemented Control Functions 


Control Functions 

• inquire^oit tput_capab ilities 

• inquire_s€lected^surfaces 

• set_immediate^visibility 

• make_pictitre_current 

• inqmre_controLstatus 

• set^visibilities 

• log^error 



Table A-5: Unimplemented Escape Functions 



Escape Functions 

• escape 


• inquire^escape 

. Other Differences 




Text; SunCore does not have the charplane primitive attribute; instead, the charpath, 
charup, and charspace attributes are used to specify text orientation as described in the manual. 
The current release of SunCore has no STROKE precision text and no text justification. The 
mquire_text^eztent^B and inquire_text^€xient^S functions do not take a view surface name as an 
argument. The text enquiry functions only return meaningful values when the current charprc’ 
cision attribute is CHARACTER. 
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o 


Raster Extensions: SunCore contains several of the proposed raster extensions to the 

ACM Core and other raster functions. Thus there are no color or intensity primitive attributes. 
Instead a color lookup table model is used. There are several primitive attributes which are 
indices into lookup tables. In addition, hidden surfaces are supported on color view surfaces. 
This requires a second parameter to the initialtge_view_surface function. 

Miscellaneous: SunCore adds these functions: 

set_image_translate^3j 

inquire_image_tramlate^S, 

9 et_8egment_image_translate^S, 

inqmre_8egment^image_translate_S. 

The functions: 

8 e t_prim i tive^ a ttribute8_2, 

8 e t_prim i tive_ attrib utes^S, 
inquire_primitive^attribute8_8t and 
inquire_primitwe_attribute8_3 

are replaced by the functions set_priTnitive^attribute8 and inqmre_primitive_attribute8, which are 
equivalent to the 3-D functions. 

Default values for many SunCore system parameters differ from those of the ACM Core. 

There are restrictions on 8et_world_coordinate^matrix_2 and 8et_world_coordtnate_matriz_3 as 
described in the manual. 

As described in the manual, some of the echo types for input functions in the ACM Core are not 
implemented. 

The marker symbol primitive attribute deviates from the ACM Core as described in the manual. 

Batching of updates only applies to dynamic segment attributes as described in the manual. 

View surfaces initialized for hidden-surface elimination do not support dynamic segment attri¬ 
butes of highlighting, transformation, or translation. mitialize^view_8urface can optionally 
suppress clearing the view surface when it is initialized. 
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Appendix B 


SunCore View Surfaces 


SunCore supports several types of view surfaces and multiple simultaneous instances of any 
type, subject to the hardware resources of the workstation on which a SunCore program is 
being run. The current release allows up to five view surfaces to be active at any time. This 
appendix gives implementation details of SunCore view surfaces and provides information on 
initializing them. 


B.l. The vwsurf Structure 

View surface names in SunCore are structures. The following declaration and definitions are 
contained in the header file / usrf include f user core *h: 

tdefine DEVNAMESIZE 20 

struct vwsurf •{ 

char screenname[DEVNAMESIZE]; 

char windowname[DEVNAMESIZE]; 

int windowfd; 

int (*dd)(); 

int instance; 

int cmapsize; 

char cmapname[DEVNAMESIZE]; 
int flags; 
char **ptr; 

}; 


#defino NULL^VWSURF O, 0, 0, O, O, 0} 

#defino DEFAULT^VWSURF (ddname) {*'**, 0, ddnamo, O, O, . O, 0> 

tdefine VWSURF_NEWFLG 1 

After initialization via the function initialize^view^snrfaee, a vweurf structure represents a 
specific instantiation of a particular type of view surface. The elements of the vwsurf structure 
completely characterize that instantiation and/or provide information used to initialize the view 
surface. This appendix refers to members of the vwsurf structure using the standard C notation, 
as if the declaration 

struct vwsurf vwsurf; 
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had been given. 
vw9urf.screenname 

is a character string which is the name of the physical device on which the view surface 
appears (for example, f devfcgoneO). 

vwsurf.windowname 

is a character string which is the name of a window device which has been opened for 
display of the output primitives directed to the view surface (for example, /dev/winlO). 

vwsurf. windowfd 

is the file descriptor corresponding to this device. Since, for all current SunCore view sur¬ 
face types, output display and input device echoing are accomplished through window sys¬ 
tem routines, these members of the structure are valid even for raw output devices. 

vwsurf.dd 

is the name of the device-independent/device-dependent interface routine through which 
graphics output to the view surface will pass. This routine defines the view surface type. 
The current SunCore view surface types are described below. 

vwsurf. instance 

identifies the instantiation of a view surface type. It should be set to 0 prior to calling 
initialize^view_surface. SunCore will set this value appropriately if the initialization is suc¬ 
cessful. 

vwsurf.cmapsize 

defines the size of the color lookup table for the view surface, and the character string 
vwsurf.cmapname gives its name, which can be used to share a color map between two or 
more view surfaces on the same physical device. These elements of the vwsurf structure are 
used only for view surfaces on color devices. Their use is described more fully below. 

vwsurf.flags 

is a field of one-bit flags. Currently, only one flag, VWSURF_NEWFLG, is defined; this flag is 
described below. 

vwsurf ptr 

is a pointer to an array of character pointers. The array should be terminated by a null 
pointer. The strings pointed to by the array contain optional information which may be 
used to initialize the view surface. Details are provided below. 


B.2. View Surface Types 

A view surface type in SunCore is the name of the driver routine for the device- 
independent/device-dependent interface. The name of the routine corresponding to the desired 
view surface type should be put into vwsurf.dd prior to calling initialize^view_surface (see the 
programming examples in Chapters 1 and 8). 

The current release of SunCore has six view surface types: 

bwldd The Sun-1 monochrome bitmap display used as a raw device. 

bwSdd The Sun-2 monochrome bitmap display used as a raw device. 

cgldd The Sun-1 color graphics display used as a raw device. 
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cg2dd The Sun-2 color graphics display used as a raw device. 

pixwindd A monochrome (one bit deep) graphics window within the Suntools window environ¬ 
ment. This window may appear on either a color or monochrome display. 

cgpizwmdd A color graphics window within the Suntools window environment. This window 
must appear on a color display. 

Only view surface types cgldd, cgBdd, and support hidden surface removal. 


The term ‘raw device’ above implies that the physical device specified by vw»urf.screenname is 
used completely and only for display of graphics output directed to one view surface. This 
allows somewhat more efficient display of output primitives. It also implies that the user has not 
started up a Suntools window environment using the device as a desktop. 

Low-level device-dependent routines are not part of SunCore. For the sake of efficiency, such 
routines are necessary for some applications. The Programmer’s Reference Manual for the Sun 
Window System contains information on low-level routines corresponding to bwldd, bw2dd, 
cgldd, and cg2dd (the ‘pixrect’ level) and pixwindd and cgpixwindd (the ‘pixwin’ level). 


B.3. Choosing a View Surface Type within an Application Pro¬ 
gram 

It may be desirable to write application programs which use different view surface types depend¬ 
ing on the environment. The next two subsections provide examples of ways to do this. The 
next subsection illustrates using a Shell variable, and the subsection after that uses the 
get_view_sur face function to do the job in a more general way. 

B.3A. Using Shell Variables to Determine the Environment 

Examining a Shell environment variable is one way to determine which environment a program 
is running in. The following example illustrates using either a bwBdd (raw Sun-2 monochrome 
display) or a pixwindd (monochrome window) view surface depending on whether the user is 
currently in the Suntools window environment. The \VINDOW31E environment variable is nor¬ 
mally defined in the user’s environment if and only if the window system is being used. 
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/* 

* an axaspla of salactlng a view surfaca 

* d^ending on the current environment 

V 

Int bv2dd (); 

struct vwsurf rawsurface = DEFAULT_VWSURF(bw2dd); 
int plxwindd(); 

struct vwsurf wlndowsurface = DEFAULT_VWSURF(pixwlndd); 
main () 

struct vwsurf ^surface, *get_surface(); 



surface get_surface() ; 
initializo^view^surface(surface« FALSE); 
select^view^surface(surface); 


struct vwsurf * 9 et_ 8 urface() /* 

{ /* 

if (getenv("WINDOW_ME")) 

return(&window8urface); 

else 


function to return pointer 
to appropriate view surface 


V 

V 



> 


return(firawsurface); 


B.S,2. The get:_view_surface Funcfiott 

The SunCore library includes the get_view_surface function which a programmer can use 
to set up a view surface structure using information from command-line arguments and the 
environment. A complete listing of get_view_surface appears at the end of this section. 
get_view_surface has the following declarations for C, FORTRAN, and Pascal: 


o 
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Table B-1: Declarations of get_view_surface in C, FORTRAN, and Pascal 


Language 

Declaration 

C 

get:_viev_sur f ace (vsptr, argv) 
struct vwsurf *vsptr; 
char **argfv; 

FORTRAN 

getviewsurface(vwsurf) 

integer vwsurf(VWSURFSIZE) 

Pascal 

getviewsurface(var surfacename: vwsurf): integer; external; 


The elements of argv are pointers to null-terminated strings which are extracted from the com¬ 
mand line that started the application program. The following fragment of C code illustrates the 
use of get_view_sur face for C programs: 

main(argc, argv) 
int argc; 
char **argv; 

< 


struct vwsurf vwsurf; 


code 


if (get_view_sur face(fivwsur f, argv)) 
exit(1) ; 

initialiEe_view_surface(&vwsurf, FALSE)) 


more code 


> 

get_view_sur face returns zero (0) if it succeeds and non-zero otherwise. The vwaurf struc¬ 
ture will have vwsurf^dd and possibly vwsttrf•screenname set to appropriate values. Other ele¬ 
ments of the structure will be null — the programmer may modify them to suit the application, 
but it is not necessary. 

The only command-line option that get_view_sur face currently recognizes is the 
—d dixplay device option, where dtsplay^device is the name of the physical display device 
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(Idevifb or fdevfcgoneO for example). The vwsurf structure will be set up to run on this dev¬ 
ice. get_view_surface also determines if the window system is running on the device, and 
chooses vwsnrf,dd appropriately. 

Using get_view_surface has a disadvantage in that since it refers to all six SunCore types 
of view surfaces, any program using it will get the code for all six device-independent/device- 
dependent driver routines linked in. For this reason, the code for get_view_sur face is 
included here. SunCore programmers may wish to tailor a version of this code for particular 
machine configurations and applications. 

The code of get_view_surface contains calls on several functions from libmnwindow.a — 
the window system library. Details of these routines can be found in the Programmer's Refers 
ence Manual for the Sun Window System. 
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/* 

get_viev_Burfac« -- Detarmlnas from coxnaand-lina arguments and 

the environment a reasonable view surface 
for a SunCore program to run on. 

V 

#include <8ys/file.h> 
tincludo <sys/ioctl.h> 

#include <sun/fbio.h> 

#lnclude <stdi,o.h> 

#lnclude <sunwindow/window_Jis.h> 

♦include <usercore.h> 

int bwldd 0; 
int bw2dd () ; 
int cgldd(); 
int cg2dd0; 
int pixwindd(); 
int cgpixvindd(); 

static struct vwsurf nullvs = NULL_VWSURF; 

static char *dovchk; 
static int devhaswindows; 

int get_view_surface(vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 

int devfnd, fd, chkdevhasvindows(); 
char *wptr< dev[DEVNAMESIZE], *getenv(); 
struct screen screen; 
struct fbtype fbtype; 

*vsptr = nullvs; 
devfnd = FALSE; 
if (argv) 

/* 

If command-line arguments are passed^ process themtusing 
win^initscreenfromargv (see the Programmer’s Reference Manual 
for the Sun Window System). The only option used by 
get_view_surface is the -d option, allowing the user to 
specify the display device on which to run. 

V 

i 

win_initscreenfromargv(&8creen, argv); 
if (screen.scr_fbname[0] != *\0') 

/* -d option was found */ 
devfnd = TRUE; 

strncpy(dev, screen.scr_fbname, DEVMAMESIZE); 

/* 

Check to see if this device has a window system 
running on it. If so devhaswindows will be TRUE 


/* All six device-independent/device-dependent */ 
/* routines are referenced in this function. */ 

/* This means the linker will pull in all of them */ 
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following the call to win_enumall. win_enumall is 
a function in libsunwindow.a. It takes a function 
as its argument, and applies this function to every 
window being displayed on any screen by the window 
system. To do this it opens each window aitd passes 
the windowfd to the function. The enumeration 
continues until all windows have been tried or the 
function returns TRUE. 

V 

devchk = dev; 
devhaswindows = FALSE; 
win_enumall (chkdevhaswindows); 

> 

> 

if (!devfnd) 

/* No -d option was specified */ 
if (wptr = getenv("WINDOW_ME")) 

< 

/* 

Running in the window system. Find the device from 
which this program was started. 

V 

devhaswindows = TRUE; 

if ((fd = open (wptr, 0_RDWR, O)) < 0) 

fprint f (stderr, ”get_viow_sur face: Can’t open %s\n”, 
wptr) ; 
return (1) ; 

} 

win_screenget(fd, ^screen); 
close(fd); 

strncpyfdev, screen.scr_fbnamo, DEVNAMESIZE); 

> 

else 


Not running in the window system. Assxime device is 
/dev/fb. 

V 

devhaswindows = FALSE; 

strncpy(dev, «/dov/fb", DEVNAMESIZE); 

> 

/* Now have device name. Find device type. */ 
if ((fd = open (dev, 0_RDWR, O)) < 0) 

fprintf(stderr, ”get_view_surface: Can’t open %s\n", dev); 
return(1); 

> 

if (ioctl(fd, FBIOGTYPE, fifbtype) == -1) 

fprintf(stderr, *’get_view_surface: ioctl FBIOGTYPE failed on Xs\n", 
dev) ; 

close(fd); ^ ^ 

return (1); 
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} 

close(fd); 

/* Now have device type and know if window system is running on it. */ 
if (devhaswindows) 

switch(fbtype.fb_type) 

{ 

case FBTYPE_SUN1BW: 
case FBTYPE_SUN2BW: 

vsptr->dd = pixwindd; 
break; 

case FBTYPE_SUN1C0L0R: 
case FBTYPE_SUN2C0L0R: 

vsptr“>dd = cgpixwindd; 
break; 

default: 

fprintf(stderr, "got_view_surface: %s is unknown fbtype\n 
dev) ; 

return (1); 

> 

else 

switch ( fbtype. fb_type) 

{ 

case FBTYPE^SUNIBW: 

vsptj—>dd = bwldd; 
break; 

case FBTYPE_SUN2BW: 

vsptr->dd = bw2dd; 
break; 

case FBTYPE^SUNICOLOR: 

vsptr->dd ^ cgldd; 
break; 

case FBTYPE_SUN2C0L0R: 

vsptj—>dd = cg2dd; 
break; 

default: 

fprintf(stderr, "get_view_surfaco: %s is unknown fbtype\n 
dev) ; 

return (1); 

> 

/* Now SunCore device driver pointer is set up. */ 
if (fdevhaswindows [] devfnd) 

/* 

If no window system on device or -d option was specified, 
tell SunCore which device. Otherwise, let SunCore figure 
out the device itself from WINDOW_GFX so the default 
window will be used if desired. 

V 

strncpy(vsptr->screenname, dev, DEVNAMESIZE); 
return(O); 

} 

static int chkdevhaswindows(windowfd) 
int windowfd; 

< 
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struct scrsen wlndovscrMn; 

win_scrcN»ng«t (vindowfd, &vlndov8creon) ; 
if (strcop (dsvchk, windovscresn.scr.fbnaas) ~ 0) 

{ 

/* 

If this window is on the display device we are checking, set 
the flag TRUE. Return TRUE to terminate the enumeration. 

V 

devhaswindows = TRUE: 
return(TRUE); 

> 

return (FALSE); 

> 


B.4. Specifying a View Surface for Initialisation 

It is not necessary to specify every member of the vwaurf structure in order to initialize the view 
surface. If only vwsurf.dd is specified, SunCore will try to obtain a view surface of the specified 
type according to a default sequence. A statically allocated vwsurf structure may be set up to 
use this default by initializing the structure via the DEFAULT_VWSURF macro defined in 
usercore»h. This is a compile-time initialization. The user may exercise finer control over view 
surfaces by setting other elements of the structure as described below. Any members which are 
not specified by the user should be set to zero (the integer 0, the NULL pointer, or an empty 
string, as appropriate). 


View Surface Specification for Raw Devices 


The default action for obtaining a new view surface of a raw device type is to try to open a 
sequence of devices until one is found which is of the right type and is not already being used. 
The sequence always starts with *’/dev/fb*'. Then the following names are tried depending on 
the view surface type: 


bwldd 

bv2dd 

cgldd 

cg2dd 


"/dov/bwoneO**, 
"/dov/bwtwoO**, 
"/dov/cgoneO", 
**/dev/cgtwoO", 


"/dev/bwonol**, 
"/dev/bwtwol", 
"/dov/cgonol**, 
"/dev/cgtwol", 


"/dov/bwono9" 
** /dev/bwtwo 9 " 
"/dev/cgone9 ** 
"/dav/cgtwo 9" 


If none of the names in the sequence can be successfully opened and verified to be of the correct 
t 3 rpe and not already in use, initialize^view^surface fails. 

If the user wishes to specify a particular physical device for a view surface, he may set 
vwsurf.screenname to be the device name of that device. The same steps will be taken to try to 
open the device as for each name in the default sequence. However, if these steps fail, no other 
names will be tried, and the initialization will fail. 

vwsurf.cmapname and vwsurf.cmapsize are only used for color view surfaces. For cgidd and 
cgBddy vwsurf.cmapsize is set to 256, If vwsurf.cmapname is specified, this name is used as the 
name of the color map; otherwise SunCore will provide a unique name. 
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No flags are currently defined for use with raw devices. 

vw 9 urf.ptr provides a mechanism for passing optional initialization data to SunCore. In the 
case of raw devices, one such option is currently available — the passing of information about 
the adjacencies of physical screens. When the user creates a Sun tools window environment on a 
screen, he is also responsible for specifying the relationship of that screen to other screens also 
running Suntools for purposes of tracking the mouse across multiple screens. The 
ctnUcretn* command may be used to do this (see the User’s Manual for the Sun UNIX System). 
However, when a SunCore program initializes a new view surface on a raw screen, the user will 
not previously have been able to inform the system of this adjacency because the new screen was 
previously not in use. vwsurf.ptr may be used to pass adjacency information for the new screen. 

If vw»\irf,piT is not NULL, it should point to an array of character pointers. Only the first 
pointer in this array will be used. It should point to a string which is the pathname of a file con¬ 
taining information about the adjacencies of physical display devices. When the user sets up his 
display devices on his desk he may create a file describing the layout of these devices. For exam¬ 
ple, the following lines describe a system with two screens, the console frame buffer on the left 
(which might be either a Sun-1 or a Sun-2 monochrome bitmap display) and a Sun color graphics 
display on the right: 

/dov/fb 

R: /dev/cgoneO 

/dev/cgonoO 

L: /dev/fb 

By convention, litvjfb is the console frame buffer and IdevIcgoncO is the first Sun color ^graph¬ 
ics display on a system. For each display device in the system, there should be one line giving its 
name, followed by several lines giving the directions and names of ail adjacent screens. Thus all 
four lines above are necessary, not just the first two. Directions may be indicated as R, L, T, 
and B for right, left, top, and bottom, or as N, S, E, and W for north, south, east, and west. 


B.4 S. View Surface Specification for Window Devices 

The default action for obtaining a new view surface of type pizmndd or cgpixwindd is to first 
test whether the window referred to by the Shell environment variable WINDOW_GFX is already 
in use as a view surface. If not, a blanket window is inserted over the WINDOW_GFX window and 
this blanket window becomes the view surface. If WINDOW_GFX has already been used in this 
manner, the program /usr/suntool/coretool is invoked to create a new window on the same phy¬ 
sical display device as WINDOW^GFX. This new window becomes the view surface. Thus, if a 
SunCore program is run from the tty subwindow of a Graphics Tool, the first default view sur¬ 
face will occupy the display space covered by the graphics subwindow of the tool. Subsequent 
default view surfaces will appear as graphics windows, each within a separate Core Tool on the 
same screen as the Graphics Tool. 

This default action may be circumvented in two ways. If vwsurf.flags has the VWSURF_NEWFLa 
set, no attempt is made to take over WINDOW.GFX. A new window within a Core Tool is opened 
on the same screen as WINDOW_GFX. If vwsurfiscreenname is non-empty, a new window within 
a Core Tool is opened on the screen specified by vwsurf.screenname, provided this device exists 
and has a Suntools window environment running on it. 

For view surfaces of t 3 rpe egpiiwindd, vwsurf.emapsize and vwsurfiemapname provide a means 
of specifying and sharing color maps. The color map facilities of the Sun Window System are 
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used to control color maps for cgphtnndd view surfaces (see the Programmer’s Reference 
Manual for the Sun Window System for details). The user may specify a color map size of 0, in 
which case a color map of length 2 will be used. Otherwise, vw*urf»emapiize should be a power 
of 2 between 2 and 256. The user may specify a null color map name, in which case SunCore 
will provide a unique name. Otherwise, SunCore will check vwsurf.emapname against the 
names of the color maps for all windows currently displayed on the physical device on which the 
new view surface is to appear. If a matching name is found, that color map will be used (even if 
its size differs from vwgurf.cmapsize) and this map is shared among all windows on the device 
which reference that name. If the user specified a null name or the specified name does not 
match any current window’s color map name, a new color map is allocated with the given size. 
The injlices for each cgpizwindd view surface’s color map run from 0 to vw6urf.cmapsize—l. 
The current release of the Sun Window System enforces the restrictions that entry 0 of the color 
map ife the background color for the desktop containing the window and entry 
vwsurf.pmapsize—l is the foreground color. The default background color for a desktop is 
white, and the default foreground color is black. 

Currently, one optional string of initialization data may be passed to initialize^view^zurfacc. If 
vwsurf.ptr is non-NULL, it should point to an array of character pointers, only the first of which 
will be used. The pointer should point to a string containing position and size information for a 
Core Tool which may be started up to provide a window for the new view surface. (If the 
WIND0W_GFX window is taken over by this new view surface and thus no Core Tool is started, 
the string will be ignored.) The string should consist of nine integers, separated by commas: 

**nl,nt,nw, nh, il, it, iw, ih, I" 

nl, and nt give the initial position of the top left corner of the Core Tool in its normal form, nw 
and nh §ive the initial width and height. The numbers are given in screen coordinates, wl|ere (0, 
0) is the upper left corner, il, it, iw, and ih give the same initial information for the iconic form 
of the tool. I is a boolean flag which should be non-zero if the tool is to be started in its iconic 
form. 


B.5. Input Considerations 

SunCore uses window system routines to obtain user input from the keyboard and mouse, no 
matter what mix of raw device view surfaces and window device view surfaces the user has ini¬ 
tialized. For purposes of input, a raw device view surface behaves just like a window device 
view surface; it exists as a window within the window system’s data structures, and the user may 
direct input to the window simply by positioning the mouse over it. The facts that window sys¬ 
tem input is directed to different windows depending on the location of the mouse and that the 
mouse position in the window system is reported in the coordinates of the window underlying the 
mouse have implications for the SunCore input functions. 

For SunCore programs which are invoked from a window within the Suntools window environ¬ 
ment, whenever the KEYBOARD device is initialized, awaitjkeyboard will return characters typed 
when the mouse is located over any initialized view surface (belonging to a single user process) 
or over the tty subwindow from which the program was started. For programs run from outside 
a window environment, awaitjceyboard will return all characters typed on the keyboard, pro¬ 
vided the KEYBOARD device is initialized. 

The ACM Core specification defines input and output to be completely orthogonal functions. 
Thus, it is possible to initialize a locator device and read from it without ever initializing a view 
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surface. SunCore uses the mouse as the LOCATOR, STROKE, PICK, VALUATOR, and BUTTON dev¬ 
ices. The only way SunCore can obtain mouse position and button click information to emulate 
these logical devices is to take input from a window. SunCore will return valid data in response 
to input requests for the LOCATOR, STROKE, PICK, and VALUATOR devices only when the user has 
associated these devices with an initialized view surface via the sot_echo_surfaco function. 
Because all SunCore view surfaces are instantiations of generic view surface types, there is no 
default echo surface for any input device. The $et^eeho^$uffact function will accept a NULL 
pointer as its inrfact_name argument to allow the programmer to end the association of an 
input device with a view surface. Any input device may be echoed on any view surface indepen¬ 
dently of any other input device. 

The input functions await^ttn^button^get^locator^ff, await^strokt^B, AW<tit_ptck, and 
await_anj;_buUon^illct_valuator will only use mouse input which the user directs to the window 
which is the echo surface for the indicated LOCATOR, STROKE, PICK, or VALUATOR device. This 
included both position and button click input, so that the functions which are terminated by but¬ 
ton clicks will terminate only when a button click occurs within the proper window (or a timeout 
occurs) Which buttons are listened to is still controlled by individually initializing or terminat¬ 
ing each BUTTON device. 

The user may also use set_ecko_»urfaee to choose from which window button clicks should be 
reported for a BUTTON device when the await_button function is called; alternatively, if the echo 
surface for a BUTTON device is NULL, await_button will check for button clicks from any view 
surface associated with a LOCATOR, STROKE, PICK, or VALUATOR device. 

Note that the resolution obtained from a LOCATOR, STROKE, PICK, or VALUATOR device is limited 
by the width and/or height of its echo surface window, since mouse position information is pro¬ 
vided by window system input routines in terms of window coordinates. 


B.6. Notes on Window Device View Surfaces 

Graphics primitives drawn on a view surface as part of a temporary segment normally '•emain 
visible on the view surface until a new-frame action occurs. For view surfaces which are win¬ 
dows within the Suntools window environment, several user actions can cause the view surface to 
be redrawn. Such actions include stretching the enclosing tool, exposing a previously obscured 
portion of the tool, and changing from the iconic form of the tool to the normal form. When the 
view surface is redrawn in this manner, all output primitives which previously appeared as part 
of temporary segments will disappear. 

When a SunCore program is run from a Shell Tool, WINDOW_GFX is normally set to be the 
tool’s tty subwindow. If this window is taken over and blanketed to serve as a view surface, out¬ 
put directed to the tty subwindow (for example, stdout and stderr, including SunCore error 
messages) will not be visible because the blanket window obscures the tty subwindow. When the 
program terminates or the view surface is terminated, any portion of this output which has not 
scrolled out of the subwindow will be visible. The fact that the tty subwindow is obscured also 
means that there is no way to type characters to that window, so that stdin will never see any 
input. However, if the KEYBOARD device is initialized, special characters, such as interrupt and 
suspend, typed to the blanket window will be recognized and will have their normal effect on the 
user process. 
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Alphabetical SunCore C Function Reference 


This appendix contains an alphabetical list of SunCore functions and their arguments 
definitions. SunCore programs written in C must contain the statement: 

#include <usercore.h> 

at the start of each compilation unit. Programs are then compiled and linked with a C compiler 
command line like: 

tutorial% cc files — Icore —leonwindow —Iplxrect —1« 


C*l. Alphabetical List of C Interfaces 




allocato^raster(raster) 
struct { 

int width, height, depth; 
short *bits; } *raster; 

avait_any_button (tline, button_nuinber) 
int time; 

int *button_number; 


awalt_any_button_get_locator_2 (time, locator^number, button__n\iinber, x, y) 
int time; 

int locator_number; 
int *button_number; 
float *x, *y; 


await_any_button_get_valuator(time, valuator^number, button_number, value) 
int time; 

int valuator_n\Junbor; 
int *button_number; 
float *value; 


avait_keyboard(time, keyboard_n\imber, input_string, length) 
int time; 

int keyboard^number; 
char •input_string; 
int *length; 
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await_pick(time, pick_number, segment^name, pick_id) 
int time; 
int pick_nuinber; 
int * segment_name; 
int *pick_id; 



await_stroke_2(time, stroke_niimber, array_size, x_array, y_array, number_points) 
int time; 

int stroke_n\imber; 
int array_size; 
float x_array[]; 
float y_array[]; 
int *number_points; 

begin_batch_of_updates() 

close_retained_segment() 

close_temporary_seginent () 


create_retained_SGgment(segment_name) 
int segment_namG; 


create_terrporary_segment () 



d©fine_color_indices(surface_name, il, i2, red_array, grGen_array, blu©_array) 
struct vwsurf *surface_namo; 
int il, i2; 

float red_array[], green_array[], blue_array[]; 


delet©_all_retained_segments() 

delete_retained_segment(segment_name) 
int segment_name; 

deselect_view_sur face(sur face_name) 
struct vwsurf *surface_name; 


end_batch_of_updat©s() 
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filo_to_raster(fd, raster, map) 
int fd; 
struct •{ 

int width, height, depth; 

short ‘bits; } ‘raster; struct ■( 

int type; 

int nbytes; 

char ‘data; )■ ‘map; 

free_raster(raster) 
struct ■{ 

int width, height, depth; 
short ‘bits; )• ‘raster; 


get_mouse_state(device_class, device_nuinber, x, y, buttons) 
int device_class; 
int device^number; 
float ‘x, *y; 
int ‘buttons; 

get_raster(surfaco_name, xmin, xmax, ymin, ymax, x, y, raster) 
struct vwsurf ‘surface_name; 
float xmin, ymin, xmax, ymax; 
int X, y; struct •( 
int width, height, depth; 
short ‘bits; }• ‘raster; 


initializo^core (output_level, input^level, dimension) 
int output^level; 
int input_level; 
int dimension; 

initialize_device(device_class, devico_number) 
int device_class; 
int device_number; 

initialize_view_surface(surface_name, type) 
struct vwsurf ‘surface_name; 
int type; 


inquire^charjust(just) 
int ‘just; 

inquire_charpath^2(dx, dy) 
float ‘dx, ‘dy; 

inquire_charpath_3(dx, dy, dz) 
float ‘dx, ‘dy, ‘dz; 
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inquire_charprecision(charprecision) 
int * charprecision; 



inquire_charsizo(charwidth, charhoight) 
float *charwidth, *charheight; 


inquire_charspaco(charspace) 
float *charspace; 


inquire_charup_2(dx, dy) 
float *dx, *dy; 

inquire_charup_3(dx, dy, dz) 
float *dx, *dy, *dz; 


inquire_color_indices (sur face_naine, il, i2, 
struct vwsurf *surface_name; 
int il, i2; 
float red_array[]; 
float green_array[]; 
float blue_array[]; 

inquire_current_posltion_2(x, y) 
float *x, *y; 

inquire_current_position_3(x, y, z) 
float *x, *y, *z; 


red_array, groen_array, blue_array) 



inquire_detectabi1ity(detectabi1ity) 
int * detectabi1ity; 

inquire_echo(device_class, device_nuinber, echo_type) 
int device_class; 
int device_nuinber; 
int *echo_type; 


inquire_echo_position(device_class, device_nuinber, echo_x, echo_y) 
int device_class; 
int device_nuniber; 
float *echo_x; 
float *echo_y; 

inquire_echo_surface (device_class, devico_nuinber, sur face_nanie) 
int device_class; 
int device_number; 
struct vwsurf *surfaco^name; 
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inquirG_fill_index(index) 
int *index; 


inquire_font(font) 
int * font; 


inquire_highlighting(highlighting) 
int *highlighting; 


inquire_image_transformation_2(sx, sy, a, tx, ty) 
float *sx, *sy; 
float *a; 
float *tx, *ty; 

inquire_image_transformation_3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
float *sx, *sy, *sz; 
float *ax, *ay, *az; 
float *tx, *ty, *tz; 



lnquire_image_trans formation_type(type) 
int *type; 

inquire_image_translate_2(tx, ty) 
float *tx, *ty; 

inquire_image_translate_3(tx, ty, tz) 
float *tx, *ty, *tz; 


inquire_inverse_composite_jnatrix(array) 
float array[4][43; 

inquire_keyboard(l<eyboard_n\imber, buffer_size, initial_string, 
lnitial_cursor_positlon) 
int keyboard_number; 
int *buffer_size; 
char *initial_string; 
int *lnitial_cursor_position; 

inquire_line_index(index) 
int *index; 



inquire_linestyle(linestyle) 
int *1inestyle; 

inquire_linewidth(linewidth) 
float *linewidth; 
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inquire_locator_2(locator^number, x, y) 
int iocator_nuinber; 
float *x; 
float *y; 



inquire_jnarker_synibol (symbol) 
int *symbol; 


inquiro_ndc_spac©_2(width, height) 
float *width, ^height; 


inquire_ndc_space_3(width, height, depth) 
float *width, ‘height, ‘depth; 

inquire_open_retained_s©gment(segment_name) 
int ‘segment_name; 


inquire_open_tenporary_segment(open) 
int ‘open; 

inquire_pen(pen) 
int ‘pen; 


inquire_pick_id(pick_id) 
int *pick_id; 

inquire_polygon_edge_styl©(style) 
int ‘style; 


inquire_polygon_int©rior_stylo(style) 
int ‘style; 



inquire_primitive_attributes(attributes) 
struct •{ 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float 1inwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; )■ ‘attributes; 
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inquire__projection(projection_typo, dx, dy, dz) 
int *projection_typo; 
float *dx, *dy, *dz; 


inquire_rasterop(rop) 
int *rop; 


inquire_retained_segment_names(array_size, name_array, number_of_seginents) 
int array_size; 
int name_array[]; 
int * number_o f_segments; 


inquire_retained_segmont_surfaces(segment^name^ array_size, view_surface_array, 

number_o f_sur faces) 

int segment^name; 
int array_size; 

struct vwsurf view_surface_array[]; 
int *number_o f_sur faces; 



inquire_segiixent..detectabi 1 ity (segmont_namo, detectabi 1 ity) 
int seginent_name; 
int *detectabi1ity; 

inquire_segment_highlighting(segment^namo, highlighting) 
int segment..name; 
int ‘highlighting; 



inquire_segment_image_transformation. 
int segment_name; 
float *sx; 
float *sy; 
float *a; 
float *tx; 
float *ty; 

inquire_segment_image_transformation. 

int segment_name; 
float *sx; 
float *sy; 
float ‘sz; 
float *ax; 
float *ay; 
float ‘az; 
float *tx; 
float *ty; 
float *tz; 


.2 (segment_name, sx, sy, a, tx, ty) 


.3(segmont_name, sx^ sy, sz, ax, ay, az, 
tx, ty, tz) 
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inquire_segment_image_trans formation_typo (segment^name, type) 
int segment_name; 
int *typo; 

inquire_segment_image_translato_2(segment^namo, tx, ty) 
int segment^name; 
float *tx; 
float *ty; 

inquire_segment_image_translate_3(segment_name, tx, ty, tz) 
int segment_name; 
float *tx; 
float *ty; 
float *tz; 



inquire_segment_visibillty(segment_namo, visibility) 
int segment^name; 
int ‘visibility; 


inquire_stroke{stroke_nuinber, buffer_size, distance, time) 
int stroke_number; 
int *bu ffer^size; 
float ‘distance; 
int ‘time; 


inquire_text_extent_2(string, dx, dy) 
char ‘string; 
float ‘dx, *dy; 

inquiro_text_extent_3(string, dx, dy, dz) 
char ‘string; 
float ‘dx, ‘dy, ‘dz; 



inquire_text_index(index) 
int ‘index; 


inquire_valuator(valuator_nuinber, initial_value, low, high) 
int valuator_number; 
float *initial_value; 
float ‘low; 
float ‘high; 


inquire_view_depth(front_distance, back_distance) 
float * front_distanco, ‘back_distance; 


inquire_view_ 4 >lane_distance(view_distance) 
float *view_distance; 
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lnquire_view_plane_normal (dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_view_reference_43oint(x, y, z) 
float *x, *y, *z; 

inquire_view_up_2(dx, dy) 
float *dx, *dy; 


inquire_view_up_3(dx, dy, dz) 
float *dx, *dy, *dz; 

inquire„viewing_control_parameters(windowclip, frontclip, backclip, type) 
int *windowclip; 
int *frontclip; 
int *backclip; 
int *type; 

inquire_viewing_parameters(view_parameters) 
struct { 

float vwrefpt[3]; 
float vwplnorm[3]; 
float viewdis; 
float frontdis; 
float backdis; 
int projtypo; 
float projdir[3]; 
float window[4]; 
float vwupdir[3]; 

float viewport [6] ; )> *view_parameters; 

inquire_viewport_2(xmin, xmax, ymin, ymax) 
float *xmin, *xmax; 
float *ymin, *yinax; 

inquire_viewport^3(xmin, xmax, ymin, ymax, zmin, zmax) 
float *xmin, *xinax; 
float *ymin, *ymax; 
float *zmin, *zmax; 

inquire_visibllity(visibility) 
int *visibility; 

inquiro_window(umin, umax, vmin, vmax) 
float *umin, *uinax; 
float *vmin, ‘vmax; 
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inquire_world„coordinate_iiiatrix_2 (array) 
float array[3][3]; 


inquire_world_coordinato_matrix_3 (array) 
float array[4][4]; 

line_abs_2 (x, y) 
float X, y; 


line_abs_3(x, y. z) 
float X, y, z; 

line_rel_2(dx, dy) 
float dx, dy; 


line_rel_3(dx, dy, dz) 
float dx, dy, dz; 


inap_ndc_to_world_2(ndcx, ndcy, wldx, wldy) 
float ndcx, ndcy; 
float *wldx, *wldy; 

map_ndc_to_world_3(ndcx, ndcy, ndcz, wldx, wldy,’ wldz) 
float ndcx, ndcy, ndcz; 
float *wldx, *wldy, *wldz; 


inap_world_to_ndc_2(wldx, wldy, ndcx, ndcy) 
float wldx, wldy; 
float *ndcx, *ndcy; 

inap_world_to_ndc_3(wldx, wldy, wldz, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz; 
float *ndcx, ^ndcy, *ndcz; 


marker_abs_2(x, y) 
float X, y; 


marker_abs_3 (x, y, z) 
float X, y, z; 

niarker_re 1_2 (dx, dy) 
float dx, dy; 


marker_rel_3(dx, dy, dz) 
float dx, dy, dz; 
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inove_abs_2 (x, y) 
float X, y; 

inove_abs_3 (x, y, z) 
float X, y, z; 

move_rel_2(dx, dy) 
float dx, dy; 


move_rel_3(dx, dy, dz) 
float dx, dy, dz; 

new_ frame () 

polygon_abs__2 (x_array, y_array, n) 
float x_array[], y_array[]; 
int n; 


polygon„abs_3 (x_array, y_array, z_array, n) 
float x_array[3 , y_aJ'*'ay[] , z_array[] ; 
Int n; 



polygon_abs_3(x_array, y_array, z_array, n) 
float x_array[], y_array[], z_array[] ; 
Int n; 


polygon_rel_2 (dx_array, dy_array, n) 
float dx_array[], dy_array[]; 
int n; 


polygon_rel_3 (dx_array, dy_array, dz_array, n) 
float dx__array[] , dy_array[3 , dz_array[] ; 
int n; 


polylinG_abs_2 (x_array, y_array, n) 
float x_array[], y_array[]; 
int n; 


polyline_abs_3(x_array, y_array, z^array, n) 
float x_array[], y_array[], z_array[]; 
int n; 

polylinG_abs_3(x_array, y_array, z_array, n) 
float x_array[] , y_array[] , z_array[] ; 
int n; 
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polyline_rel_2(dx^array, dy_array, n) 
float dx_array[], dy_array[]; 
int n; 


polyline_rel_3(dx_array, dy^array, dz_array, n) 
float dx_array[], dy_array[], dz_array[]; 
int n; 


polymarker_abs_2 (x_array, y_array, n) 
float x_array[], y_array[3; 
int n; 


polymarker_abs_3(x_array, y_array, z_array, n) 
float x_array[3, y_array[] , z_array[]; 
int n; 


polymarker_rel_2(dx_array, dy_array, n) 
float dx_array[], dy_array[]; 
int n; 


polymarker_rel_3{dx_array, dy_array, dz_array, n) 
float dx_array[] , dy_array[] , dz_array[] ; 
int n; 


print_error (”Your message”, error ^.number); 
int error^number; 


put_raster(raster) 
struct ■{ 

int width, height, depth; 
short *bits; } ‘raster; 


raster_to_file (raster, map, fd, replicate) 
struct >( 

int width, height, depth; 

short ‘bits; > ‘raster; struct ■( 

int type; 

int nbytes; 

char ‘data; } ‘map; 

int fd; 

int replicate; 


rename_retained_segment(segmont__name, newname) 
int segment_name; 
int newname; 


report_most_recent_error (error_nuinber) 
int *error_number; 
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restore^segment(segment_name, filename) 
int segment^name; 
char * filename; 

save_5egment(segment_name, filename) 
int segment_name; 
char * filename; 

select„view_sur face(sur face_namo) 
struct vwsurf *surface_name; 

set_back_plano_clipping{back_on_o f f) 
int back_on_off; 

set_charjust(just) 
int j ust; 

set_charpath^2(dx, dy) 
float dx, dy; 

set_charpath_3(dx, dy, dz) 
float dx, dy, dz; 

set_charprecision(charprecision) 
int charprecision; 

set_charsize(charwidth, charheight) 
float charwidth, charheight; 

set_charspace(charspace) 
float charspace; 

set_charup_2(dx, dy) 
float dx, dy; 

set_charup_3(dx, dy, dz) 
float dx, dy, dz; 

set_coordinate_system_type(type) 
int type; 

set_detect abi1ity(detectabi1ity) 
int detectability; 

set_drag(mode) 
int mode; 
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set^echo (device^class, <3evico_nuinber, echo_type) 
Int devlce^class; 
int dovice^number; 
int echo^typo; 



set_ocho_gfroup (device_class, dovice_nuinbor_array, n, ©cho_type) 
int device_class; 
int device_nuinber_array [] ; 
int n; 

int ech<3_type; 


set_echo_position(devico_class, dovico^number, echo_x, echo_y) 
int d©vice_class; 
int device^number; 
float echo_x; 
float ocho_y; 


set_echo_surface(devico^class, devlce_number, surface_name) 
int devic©_class; 
int device^number; 
struct vwsurf ‘surface^narae; 


set^fill_index (index) 
int index; 


set_font(font) 
int font; 



set_ front_p1ane_c1ipping(front_on_o f f) 
int front_on_off; 


sot_highlighting(highlighting) 
int highlighting; 


set_image_^transformation_2 (sx, sy, a, tx, ty) 
float sx, sy; 
float a; 
float tx, ty; 

iset_imago^transformation_3(sx, sy, S2, ax, ay, az, tx, ty, tz) 


float 

sx. 

sy. 

sz; 

float 

ax. 

ay. 

az; 

float 

tx. 

ty. 

tz; 


set_imago_transformation__typo (type) 
int typo; 

c 


ai4 
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set_image_1:ranslate_2 (tx, ty) 
float tx, ty; 

set_image_translate_3(tx, ty, tz) 
float tx, ty, tz; 


set_keyboard(keyboard_nuinber, buffer_sizo, initlal_string, 
initial_cursor„position) 
int keyboard_niimber; 
int buffer_size; 
char *initial_string; 
int initial_cursor_position; 


sot_light_direction(dx, dy, dz) 
float dx, dy, dz; 


set_line_index(index) 
int index; 



set_linestyle(linestyle) 
int linestyle; 


set^linewidth(linewidth) 
float linewidth; 


set_locator_2 (locator_nuinber, x, y) 
int locator^number; 
float x; 
float y; 


set_niarker_symbol (marker) 
int marker; 


set_ndc_space_2(width, height) 
float width, height; 

set_ndc_space_3(width, height, depth) 
float width, height, depth; 

set_output_clipping(on_off) 
int on_off; 


set^en (pen) 
int pen; 
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set^ick (pick_number, aperture) 
int pick^numbor; 
float aperture; 


set_pick_id(pick_id) 
int pick_id; 


set_polygon_edge_stylo(style) 
int style; 


set_polygon_interior_style(style) 
int style; 

set_primitive_attributes(&PRIMATTS) 

5et_primitive_attributes(attributes) 
struct •{ 

int 1ineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float 1inwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; y ^attributes; 

set_projection(projection, dx_proj, dy_proj, dz_proj) 
int projection; 

float dx^roj, dy_45roj , dz_proj ; 


set_rasterop(rop) 
int rop; 

set_segment_detectability(segment_name, detectability) 
int segment_name; 
int detectability; 

set_segment_highlighting(segment_najne, highlighting) 
int segment^name; 
int highlighting; 
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set_segment_image_transformation_2 (segment^namo^ sx, sy, a, tx, ty) 
int segment_name; 
float sx; 
float sy; 
float a; 
float tx; 
float ty; 


set_seginent_image_transformatlon_3 (segment_name, sx, sy, sz, ax, ay, az 

tx, ty, tz) 

int segment_name; 

float sx; 

float sy; 

float sz; 

float ax; 

float ay; 

float az; 

float tx; 

float ty; 

float tz; 



set_segment_lmago_translat©_2(segment_naine, tx, ty) 
int segment_name; 
float tx; 
float ty; 


set_segment_iniag©_translate_3(segment_namo, tx, 
int segment_nam©; 
float tx; 
float ty; 
float tz; 


ty, tz) 



set_segment_visibility(segment_name, visibility) 
int segment_naino; 
int visibility; 


set_shading_paramGt©rs(ambient, diffuse, specular, flood, bun^j, hue, style) 
float ambient; 
float diffuse; 
float specular; 
float flood; 
float bump; 
int hue; 
int style; 


set_stroke(stroke_number, buffer_sizo, distance, time) 
int stroke_numbBr; 
int buffor_size; 
float distance; 
int time; 
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set_text_index(index) 
int index; 


set_valuat:or(valuator^number, initial_value, low, high) 
int valuator_number; 
float initial_value; 
float low; 
float high; 



set_vertex_indices(color_index_list, n) 
int color_index_list[]; 
int n; 


set_vertox_normals(xlist, ylist, zlist, n) 
float xlist [], ylist [], zlist []; 
int n; 


set_view_depth (front_distance, back_distance) 
float front_distance, back_distanc©; 


^set_vi©w_plan©_distance(distance) 
float distance; 


set_view_plane_normal(dx„norm, dy_norm, 
float dx_norm, dy_norm, dz_norm; 


dz_norm) 


S6t_view_refer©nce_point(x, y, z) 
float X, y, z; 


set_view__up_2 (dx, dy) 
float dx, dy; 


s©t_view_up_3(dx_up, dy_up, dz_up) 
float dx_up, dy_up, dz_up; 


set_viewing_parameters(vi©w_ 4 >arameters) 
struct •{ 

float vwrefpt[33; 
float vwplnorm[3]; 
float viewdis; 
float frontdis; 
float backdis; 
int projtype; 
float projdir[3]; 
float window[4]; 
float vwupdir[3]; 

float viewport [6] ; y *vi©w_parainoters; 
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set_viewport_2 (xmin, xmax, ymin, ymax) 
float xmln, xmax; 
float ymin, ymax; 

set^viewport_3(xmin, xmax, ymin, ymax, zmin, zmax) 
float xmin, xmax; 
float ymin, ymax; 
float zmin, zmax; 


iset_visibility(visibility) 
int visibility; 


set_window(umin, umax, vmin, vmax) 
float umin, umax; 
float vmin, vmax; 

set_window_clipping(on_off) 
int on_off; 

set_world_coordinate_matrix_2(array) 
float array[3][3]; 



set_world_coordinate_matrix_3(array) 
float array[4][4]; 


set_zbuffer_cut(surface_name, xlist, zlist, n) 
struct vwsurf *surfaco_neune; 
float xlist [], zlist []; 
int n; 


size_raster(surface_name, xmin, xmax, ymin, ymax, raster) 
struct vwsurf *surface_namo; 
float xmin, xmax, ymin, ymax; struct ■{ 
int width, height, depth; 
short *bits; } ‘raster; 

termlnate_core() 


terminate^device(device^class, device_nuinber) 
int devico^class; 
int device_number; 


terminate_view_sur face (sur face_naine) 
struct vwsurf *surface_name; 



text(string) 

char ‘string; 
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Appendix D 


Using SunCore with Fortran-77 Programs 


All functions provided in SunCore may be called from FORTRAN-77 programs by linking them 
with the /usr/lib/libcor€77.a library. This is done by using the /77 compiler with a command 
line such as: 

tutorial%gf77 -o grab grab.f -leore77 -Icore -launwlndow -Ipixrect -Im 

where grab,/ is the FORTRAN source program. Note that /usr/lib/Ubcore,a must be linked 
with the program (the — Icoro option), and /usr/lib/libcore77,a must come before it (the 
—lcore77 option). 

Defined constants may be referenced in source programs by including 
/usr/include/f77/usercore77,h In a FORTRAN program, this must be done via a source state¬ 
ment like: 


include **/usr/include/f77/usercore77 .h** 

This include statement must be in each FORTRAN program unit which uses the defined constants, 
not just once in each source program file. The default primitive attribute structure PRIMATTS 
which is provided in usercore,h and is described in section 6.1.23 of this manual is not provided 
in usercore77.h because of FORTRAN’S restrictions on the ordering of specification statements 
and data statements. 

In the Sun release of FORTRAN-77, names are restricted to sixteen characters in length and may 
not contain the underline character. For this reason, FORTRAN programs must use abbreviated 
names to call the corresponding SunCore functions. The correspondence between the full Sun- 
Core names and the FORTRAN names appears later in this appendix. In addition, FORTRAN-77 
declarations for all SunCore functions appear at the end of this appendix. 


D.l. Programming Tips 


• The abbreviated names of the SunCore functions are less readable than the full length names 
because the underline character cannot be used in the FORTRAN names. However, since FOR¬ 
TRAN doesn’t distinguish between upper-case and lower-case letters in names, upper-case char¬ 
acters can be used to improve readability. There is an example of this later in this appendix. 

• Character strings passed from FORTRAN programs to SunCore cannot be longer than 256 
characters. 

• FORTRAN passes all arguments by reference. Although some SunCore functions receive argu¬ 
ments by value, the FORTRAN programmer need not worry about this. The interface routines 
in / U9rHib/libcore77.a handle this situation correctly. V^en in doubt, look at the FORTRAN 
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declarations for SunCore functions at the end of this appendix. 

• SunCore uses pointers in some places. For instance, view surface structures contain pointers 
to device driver functions. Also, the raster data type includes a pointer to an array of short’s 
containing the raster data. There are no pointer types in FORTRAN, but there are ways to 
handle all uses of pointers required to use SunCore. For view surface names, the following 
fragments of C code and FORTRAN code do the same thing: 



C Code 


FORTRAN Code 

struct vwsurf vsurf = NULL_VWSURF; 

integer 

vsurf(VWSURFSIZE) 

int bvldd() ; 

integer 

bwldd 


external 

bwldd 

vsurf.dd = bwldd; 

data vsurf /VWSURFSIZE*0/ 


vsurf (DDINDEX) = loc(bwldd) 

initialize_view_surface(Avsurf, FALSE); 

call InitializeVwsurf(vsurf, FALSE) 


The constants VWSURFSIZE and DDINDEX are defined in u8ercore77.k. The constant VWSURF- 
NEWFLG is also defined in visercore77.h. See appendix B for more details on view surfaces. 

As shown above, all required pointer manipulation can be done with the FORTRAN loc library 
function, which returns the address of its argument as an integer. 


SunCore function arguments which are pointers to structures can be declared as arrays in 
FORTRAN. For example, the C and FORTRAN declarations of the SunCore raster structure 
are shown below: 


C Code 

FORTRAN Code 

struct { 

int widths height, depth; 
short *bits; 

}• raster; 

integer raster(4) 

Then the following fragments of C and FORTRAN code 

are equivalent: 

C Code 

FORTRAN Code 

short data[16]; 

integer*2 data(16) 

raster.width = 16; 
raster.height = 16; 
raster.depth = 1; 
raster.bits = data; 

raster (1) = 16 
raster(2) = 16 
raster (3) = 1 
raster(4) = loc(data) 



i 

1 

f 


• Some SunCore structures contain both int’s and float’s. For instance, the argument to 
inquire_viewing_parameters contains both int’s and float’s. This can be handled in 
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FORTRAN by declaring a REAL array and an INTEGER array which are made to share 
storage by an EQUIVALENCE statement. Then following the call to the inquiry function, the 
REAL components can be accessed by using the REAL array and the INTEGER components 
accessed via the INTEGER array. 

• Since FORTRAN does not distinguish between upper-case and lower-case letters in identifiers, 
any FORTRAN program unit which includes the usercore77,h header file cannot use identifiers 
with the same spelling as any constant defined in that header file (regardless of case). 

• The filet or aster and rastertofile functions in C take an argument that is a UNDCf 
file descriptor. The corresponding argument to the FORTRAN functions is a logical unit 
number (LUN). This unit should be explicitly opened by using the FORTRAN open statement. 
I/O to the opened file should be done only via the filetoraster and rastertofile 
functions. 


D.2* Example Program 

This example is the FORTRAN equivalent of the very simple program for drawing a martini glass. 


include ”/usr/include/f77/usercore77.h" 

integer vsurf(VWSURFSIZE) 
integer bwldd 
external bwldd 

integer InitializeCore, InitializeVwsurf, SelectVwsurf 
real glassdx(9), glassdy(9) 

data glassdx /-lO.0,9.0,0.0,-14.0,30.0,-14.0,0.0, 9.0,-10.0/ 
data glassdy /0.0,1.0,19.0,15 .0,0.0,-15.0,-19.0,-1.0, 0.0/ 
data vsurf /VWSURFSIZE*0/ 

vsurf(DDINDEX) = loc(bwldd) 

if (InitializeCore(BASIC, NOINPUT, TWOD) .ne. 0) call exit(l) 

if (InitializeVwsurf(vsurf, FALSE) .no. O) call exit(2) 

if (SelectVwsurf(vsurf) .ne. O) call exit(3) 

call SetViewport2(0.125, 0.875, 0.125, 0.75) 

call SetWindow(—50.0, 50.0, —10.0, 80.0) 

call CreateTenqpSeg0 

call MoveAbs2(O.0, 0.0) 

call PolylineRel2(glassdx, glassdy, 9) 

call MoveRel2(-12.0, 33.0) 

call LineRol2(24.0, 0.0) 

call CloseXeinpSeg0 

call sleep(10) 

call DeselectVwsurf(vsurf) 

call TerminateCoreO 

end 


t UNIX is a trademark of Bell Laboratories. 
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D.3* Correspondence Between C Names and FORTRAN Names 


Correspondence Between C Names and FORTRAN Names 


Long Name 

FORTRAN Equivalent 

al locate_ras-tor 
awa it_any_bu'tton 
await_any_but:ton_get_ 1 ocator_2 
await:_any_but;ton_get_ valuator 
await_keyboard 

allocateraster 
awaitanybutton 
awtbuttongetloc2 
awtbuttongetva1 
avaitkeyboard 

await_pick 
await_stroke_2 
begin_batch_of^updates 
close_retained_segment 
close_temporary_segment 

avaitpick 
awaitstroke2 
beginbatchupdato 
closeretainseg 
c1osetempseg 

create_retained_segment 
create_temporary_segment 
de fine_co1or_indices 
delote_all_retained_segments 
delete_retained_segment 

createretainseg 
createtempseg 
de fCOlorindices 
delalIretainsegs 
delretainsegment 

ideselect_view_sur face 
'end_batch_o f_updates 
; filo_to_raster 
^free_raster 
'get_mouse_state 

dese1ectvwsur f 
endbatchupdate 
filetoraster 
freeraster 
getmousestate 

get_raster 
initiali 2 e_core 
initialize_device 
initialize_view_surface 
incjuire_char just 

getraster 
initializecore 

initializedevice 
initializevwsurf 
inqcharjust 

inquire_charpath_2 

inquire_charpath_3 

inquire_charprecision 

inc[uire_charsizo 

inc[uire_charspace 

inqcharpath2 

inqcharpath3 

inqcharprecision 

inqcharsize 

inqcharspace 

inquire_charup_2 

inquire_charup_3 

inquire_co1or_indices 

inquire_current_position_2 

inquire_current_position_3 

inqcharup2 
inqcharup3 
inqco1orindices 
inqcurrpos2 
inqcurrpos3 

incjuire^detectability 

inquiro_echo 

inqdetectabi1ity 
ingecho 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

inquire_echo_posit:ion 
incjuire_echo_sur f ace 
inciuire_ fill_index 

inqechoposition 
inqechosur face 
inqfillindex 

inqpair e_ font 
in qu i r e_hi gh 1 i ght in g 
inquiro_imago_trans formation_2 
inquire_image_trans formation_3 
inquire_image_trans formation_typo 

inqfont 

inqhigh1ighting 
inqimgtrans form2 
inqimgtrans form3 
inqimgx formtype 

inquire_iinage_translate_2 
inquire_imago_translate_3 
inquire_inverse_composite_matrix 
inquire_keybo ard 
incjuir e_ 1 ine_index 

inqimgtranslate2 
inqimgtranslate3 
inqinvcompmatrix 
inqkeyboard 
inqlineindex 

incjuire_linestyle 
inc[uir e_ 1 inewidth 
.inquire_locator_2 
.‘inquiro_marker_syinbo 1 
;inquiro_ndc_space_2 

inqlinestyle 
inqlinewidth 
inqlocator2 
inqmarkersymbo1 
incpndcspace2 

inquiro_ndc_space_3 

inquire^op en_r ot ained_se gment 

incjuire_open_temporary_seginent 

inquire_pen 

inq[uire_pick_id 

inqndcspace3 
inqopenretainseg 
inqop ent emp s e g 
inqpen 
inqpickid 

incjuir e_po ly gon_edge_sty 1 o 
inc[uire_polygon_interior_style 
inquire_primitive_attributes 
inquire_projection 
inc[uire_rasterop 

inqpolyedgesty1e 
inqpolyintrstyle 
inqprimattribs 
inqprojection 
inqrasterop , 

inquire_retained_segnient_names 
inquire_retained„segment„sur faces 
incjuire_segment_detect ability 
incpi i r e_s e gment _high lighting 
inquire_segment_image_transformation_2 

inqretainsegname 
inqretainsegsur f 
inqsegdetectab1e 
inqseghighlight 
inqsegimgxform2 

inqpaire_se gment „imago_trans formation_3 
inqpjiire_segment_image_trans formation_type 
inq[uire_segment_image_translate_2 
inquire_segment_image_trans1ate_3 
inquiro_segment_visibility 

inqsegimgx form3 
inqsegimgx frmtyp 
inqsegimgxlate2 
inqse gimgx1ate 3 
inqsegvisibi1ity 

incruire_stroke 

incfstroke 
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Long Name 

FORTRAN Equivalent 

inciuire_'text_extent:_2 

inc[t ext ext ent 2 

inquir0_text_extent_3 

inqtextextent3 

inquire_text_index 

inqtextindex 

inquire_valuator 

inqvaluator 

inqpaire_view_depth 

inqviewdepth 

inquire_view_plane_distance 

inq[vi©wp 1 anedist 

inquire_view_p1ane_norma1 

inqviewp1anenorm 

inquire_viev_re f erence_point: 

inqviewre fpoint 

inq[uire_view_up_2 

inqviewup2 

inquire_view_up_3 

inq[vi©wup3 

iinquire_viewing_cont:rol_parameters 

inqvwgcntrIparms 

'inciuire_viewing_parametors 

inqviewingparams 

iinc[uire_viewport:_2 

inqfviewport2 

'inquire_viewport_3 

inqviewport3 

inquire_visibility 

inq[visibility 

inquir©_window 

inqwindow 

inquire_vorld_coordinat:e_matrix_2 

inqwor1dmatrix2 

inquire_wor ld_coordinate_mat:rix_3 

inqyor1dmatrix3 

lino_abs_2 

lineabs2 

line_abs_3 

lineabs3 

line_rel_2 

linerel2 

line_rel_3 

linerel3 

map_ndc_to_wor1d_2 

mapndctoworld2 

inap_ndc_'to_world_3 

mapndctoworld3 

map_wor1d_to_ndc_2 

mapworldtondc2 

niap_wor 1 d_to_ndc_3 

mapworldtondc3 

marker_abs_2 

markerabs2 

marker_abs_3 

markerabs3 

mark©r_rel_2 

markerrel2 

marker_rel_3 

markerrelS 

move_abs_2 

moveabs2 

inove_abs_3 

moveabs3 

move_rel_2 

moverel2 

mov©_rel_3 

moverel3 

new_frame 

nowframe 

p o1ygon_abs_2 

polygonabs2 

polygon_abs_3 

polygonabsS 

polygon_rel_2 

polygonrel2 

polygon_rel_3 

polygonrel3 
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Long Name FORTRAN Equivalent 


poly1ine_abs_2 
poly1ine_abs_3 
polyline_rel_2 
polyline_rel_3 
po lyiaarker_abs_2 

polylineabs2 
poly1ineabs3 
polylinerel2 
polylinerel3 
polymarkerabs2 

po lyiDarker_abs_3 

polymarker„rel_2 

polymarker_rel_3 

print_error 

put_raster 

polymarkerabs3 
polymarkerrel2 
polymarkerre13 
printerror 
putraster 

raster_t:o_file 

renaiiie_retainedLsegmen't 

repor't_most:_recent:_error 

rest:ore_segment: 

save_segment 

rasterto file 

renameretainseg 

reportrecenterr 

restoresegment 

savesegment 

select_view_sur face 
set_b ack_p1ane_c1ipping 
set^charjust 
set_charpath_2 
set_charpath_3 

selectvwsurf 
setbackclip 
setcharjust 
setcharpath2 
setcharpath3 

set_charprecision 

set_charsize 

set_charspaco 

set_charup_2 

set_charup_3 

setcharprecision 

setcharsizo 

setcharspace 

setcharup2 

setcharup3 

set_coordinate_system_typo 

set_detectabi1ity 

set^drag 

iset_echo 

set_echo_group 

setcoordsystype 

setdetectability 

setdrag 

setecho 

setechogroup 

'set_echo_position 
set_echo_sur face 
set_fill_index 
set_ font 

set_ f ront_p1ane_c1ipping 

setechoposition 
setechosur face 

setfillindex 
setfont 
setfrontclip 

set_highlighting 
set_image_trans formation_2 
sot_image_tr ans formation__3 
set_image_trans formation_type 
set_image_translate_2 

sethighlighting 
setimgtrans form2 
setimgtrans form3 
setimgx formtype 
setimQrtranslate2 
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Long Name FORTRAN Equivalent 


set:_iinage_translat©_3 

setimgtrans1ate3 

set^keyboard 

setkeyboard 

set_light_direct:ion 

setlightdirect 

set_1ino_index 

sotlinoindex 

set^1inesty1e 

sot1inestylo 

set:_ 1 inewidth 

set1inewidth 

set_locator_2 

setlocator2 

set_inarker _syTiibo 1 

setmarkersymbo1 

set_ndc_space_2 

sotndcspac©2 

set_ndc_space_3 

setndcspaceS 

set:__output:_c 1 ipping 

setoutputc1ip 

set_pen 

setpen 

set_pick 

setpick 

set:_pick_id 

setpickid 

set_polygon_©dgo_sty1o 

setpolyedgestylo 

set_polygon_interior_st:yle 

setpolyintrsty1e 

set:_primit:ive_attributes 

setprimattribs 

set:_pro j ect ion 

setprojection 

set_rasterop 

setrasterop 

set__segment_detectability 

setsegdetectable 

set_segment_highlighting 

setseghighlight 

set:_segpment_iinage_transformation_2 

setsegimgx form2 

set_segment_iinage_trans format ion_3 

setsegimgx form3 

s©t_segment_image_translat©_2 

setsegimgxlate2 

set_segment_image_translate_3 

setsegimgxlate3 

,set_segment_visibility 

setsegvisibi1ity 

’set_shading_parameters 

setshadingparams 

>set_stroke 

setstroke 

set_text_index 

settextindex 

set_valuator 

sotvaluator 

set_vertex_indices 

setvertexindices 

set_vertex_norihals 

sotvertexnorma1s 

set_vi©w_depth 

setviewdepth 

set_view_plane_distance 

setviewp1anedist 

set_view_p1ane_norma1 

setviowp1anenorm 

set_view_re ference_point 

setviewre fpoint 

set_viewport_2 

setviovport2 

set_viewport_3 

setviewport3 i 

set„view„up_2 

sotviewup2 

s et_Viev_up_3 

setviewup3 


K 
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Long Name 

FORTRAN Equivalent 

se‘t_viewing_parameters 

sGtviewingparams 

set_visibility 

set_window 

set_window_c1ipping 

set_world_coordinate_matrix_2 

sot_world_coordinate_matrix_3 

setvisibility 
setwindow 
setwindowc1ip 
setworldmatrix2 

setworldmatrixS 

sot_zbuf fer_cut 

size_raster 

terminate_core 

terminate_device 

terminate_viev_sur face 

text 

setzbuf fercut 

sizeraster 

•terminatecore 

terminatedevice 
terminatevwsur f 

text 


D.4. FORTRAN Interfaces to SunCore 

Note: Although all SunCore procedures are declared here as functions, each may also be called as 
a subroutine if the user does not want to check the returned value. 

integer function allocateraster(raster) 
integer raster(4). 


integer function awaitanybutton(time, buttonnum) 
integer time, buttonnum 

integer function awtbuttongetloc2(time, locatornum, buttonnum, x, y) 
integer time, locatornum, buttonnum 
real x, y 

integer function awtbuttongetval (time,valuatornum,buttonnum,value) 
integer time, valuatornum, buttonnum 
real value 


Integer function awaitkeyboard(time, keyboardnxim, inputstring, length) 
integer time, keyboardnum 
character*(*) inputstring 
integer length 


integer function awaitpick(time, picknum, segname, pickid) 
integer time, picknum, segname, pickid 
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integer function awaitstroke2(time, strokenum, arraysize, xarray, yarray, n) 
integer time, strokenum, arraysize 
real xarray, yarray 
integer n 

integer function beginbatchupdate() 

integer function closeretainseg() 

integer function closeten¥*s®9() 

integer function createretainseg(sognamo) 
integer segname 

integer function createtenqpsegO 

integer function defcolorindices(surfacenamo, il, i2, red, green, blue) 
integer sur facename(*) 

-integer il, i2 

real red(*), green(*), blue(*) 


^integer function delallretainsegs () 

integer function delretainsegment(segname) 
integer segname 


integer function deselectvwsurf(surfacename) 
Integer sur facename ( *) 


integer function endbatchupdate() 

integer function filetoraster(rasfid, raster, map) 
integer rasfid 
integer raster(4) 
integer map(3) 


Integer function freeraster(raster) 
integer raster(4) 


integer function getmousestate(devclass, devnum, x, y, buttons) 
integer devclass, devnum 
real x, y 
integer buttons 
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integer function getraster(surfacenamo, xmin, xmax, ymin, ymax. xd, yd, raster) 

integer sur facename(*) 

real xmin, xmax, ymin, ymax 

integer xd, yd 

Integer raster(4) 


integer function initializecore(outputlevel, inputlevel, dimension) 
integer outputlevel, inputlevel, dimension 


integer function initializedevico(deviceclass, devicenum) 
integer deviceclass, devicenum 


integer function initializevwsurf (surfacename, type) 
integer sur facename(*) 
integer type 


integer function inqcharjust(just) 
integer just 

integer function inqcharpath2(dx, dy) 
real dx, dy 

integer function inqcharpathS(dx, dy, dz) 
real dx, dy, dz 


integer function inqcharprecision(charprecision) 
integer charprecision 


integer function inqcharsize(charwidth, charheight) 
real charwidth, charheight 



integer function inqcharspace(charspace) 
real charspace 

integer function inqcharup2(dx, dy) 
real dx, dy 

integer function inqcharupS(dx, dy, dz) 
real dx, dy, dz 

integer function inqcolorindices(surfacename, il, i2, red, green, blue) 
integer surfacename(*) 
integer il, i2 

real red(*), green(*), blue(*) 
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integer function inqcurrpos2(x, y) 
real x, y 

integer function inqcurrpos3(x, y, z) 
real x, y, z 

integer function inqdetectability(detectability) 
integer detectability 

integer function inqecho(deviceclass, devicenum, echotype) 
integer deviceclass^ devicenum, echotype 

integer function inqechoposition(deviceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 



integer function inqechosurfaco(doviceclass, devicenum, surfacename) 
integer deviceclass, devicenum 
integer surfacename(*) 

integer function inqfillindex(index) 
integer index 

integer function inqfont(font) 
integer font 



integer function inqhighlighting(highlighting) 
integer highlighting 

integer function inqimgtransform2(sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 

integer function inqimgtransformS(sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function inqimgxformtype(type) 
integer typo 

integer function inqimgtranslate2(tx, ty) 
real tx, ty 

integer function inqimgtranslateS(tx, ty, tz) 
real tx, ty, tz 

integer function inqinvcon^smatrix(array) 
real array(4,4) 
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integer function inqkeyboard(keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character*(*) initstring 
integer initcursor 

integer function inqlineindex(index) 
integer index 

integer function inqlinestyle(linestyle) 
integer linestyle 

integer function inqlinewidthflinewidth) 
real linewidth 


integer function inqlocator2(locatornum, x, y) 
integer locatornum 
real x, y 

integer function inqmarkersymbol (symbol) 
integer symbol 

integer function inqndcspace2(width, height) 
real width, height 

o 

integer function inqndcspace3(width, height, depth) 
real width, height, depth 

integer function inqopenretainseg(segnamo) 
integer segname 

integer function inqopenten^jseg(open) 

Integer open 

integer function inqpen(pen) 
integer pen 

integer function inqpickid(pickid) 
integer pickid 

integer function inqpolyedgestylo(style) 
integer style 

integer function inqpolyintrstylo(style) 
integer style 

o 
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integer function inqprimattribs(primattr) 
integer primattr(28) 

Note: The actual argument tn the calling program correBponding to primattr should be an array 
which can be referenced both as a real array and as an integer array in order to access both 
integer valued and real valued primitive attributes. This can be done using the equivalence 
statement. 

integer function inqprojection(projection^ dxproj, dyproj, dzproj) 
integer projection real dxproj, dyproj, dzproj 

integer function inqrasterop (rop) 
integer rop 

integer function inqretainsegname(arraysize, namearray, nxunberofsegments) 
integer arraysize, namearray (*) , nximber of segments 

integer function inqretainsegsurf(segname, arraysize, vwsurfarray, numsurf) 
integer segname, arraysize 
integer vwsurfarray(*) 

Integer numsurf 

Note: arraysize should give the number of view surface structures which can be held in vwsurfar^ 
ray. Each structure requires VWSURFSIZE elements of vwsurfarray. 


integer function inqsegdetectable(segname, detectability) 
integer segname, detectability 

integer function inqseghighlight (secpnamo, highlighting) 
integer segname, highlighting 

integer function inqsegimgxform2(segname, sx, sy, a, tx, ty) 

integer segname 

real sx, sy, a, tx, ty 

integer function inqsegimgxformS(segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function inqsegimgxfrmtyp(segname, type) 
integer segname, type 

integer function inqsegimgxlato2(segname, tx, ty) 
integer segname 
real tx, ty 
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integer function InqsegimgxlateS(segname, tx, ty, tz) 
integer segname 
real tx, ty, tz 


integer function inqsegvisibility(segname, visibility) 
integer segname, visibility 


integer function inqstroke(strokenum, bufsize, dist, time) 
integer strokenxm, bufsize 
real dist 
integer time 


integer function inqtextextent2(string, dx, dy) 
character*(*) string 
real dx, dy 


integer function inqtoxtextentS(string, dx, dy, dz) 
character*(*) string 
real dx, dy, dz 


integer function inqtextindex(index) 
integer index 



integer function inqvaluator(valuatornxim, initialvalue, low, high) 

integer valuatornum 

real initialvalue, low, high 


integer function inqviewdepth(frontdistance, backdistance) 
real frontdistance, backdistance 


integer function inqviewplanedist(viewdistance) 
real viewdistance 


integer function inqviewplanenorm(dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 

integer function inqvlewrefpoint (x, y, z) 
real x, y, z 

integer function inqviewup2(dxup, dyup) 
real dxup, dyup 

integer function inqviewupS(dxup, dyup, dzup) 
real dxup, dyup, dzup 
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integer function inqvwgcntrlparms(windowclip, frontclip, backclip, typo) 
integer windowclip, frontclip, backclip, typo 



integer function inqviewingparams(viewparans) 
real viewparams(26) 


Note: The actual argument in the calling program corresponding to viewparams should be an 
array which can be referenced both as a real array and as an integer array in order to access 
both integer valued and real valued viewing parameters. This can be done using the 
equivalence statement 


integer function incivie\^port2 (xmin, xmax, ymin, yinax) 
real xmin, xmax, ymin, ynax 


integer function inqviewportS(xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin^ xmax, ymin, ymax, zmin, zmax 

integer function inqvisibility(visibility) 
integer visibility 


integer function inqwindow(umin^ umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function inqworldmatrix2(array) 
real array(3,3) 

integer function inqworldmatrixS(array) 
real array(4,4) 

integer function lineabs2(x, y) 
real x, y 

integer function lineabs3(x, y, z) 
real x, y, z 

integer function linerel2(dx, dy) 
real dx, dy 

integer function linerel3(dx, dy, dz) 
real dx, dy, dz 

integer function mapndctovorld2(ndex, ndey, wldx, wldy) 
real ndex, ndey, wldx, wldy 
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integer function mapndctoworld3 (ndcx, ndcy, ndcz, wldx, wldy, wldz) 
real ndcx, ndcy, ndcz, wldx, wldy, wldz 


integer function mapworldtondc2(wldx, wldy, ndcx, ndcy) 
real wldx, wldy, ndcx, ndcy 


integer function iiiapworldtondc3 (wldx, wldy, wldz, ndcx, ndcy, ndcz) 
real wldx, wldy, wldz, ndcx, ndcy, ndcz 

integer function markerabs2(x, y) 
real x, y 

integer function markerabs3(x, y, z) 
real x, y, z 

integer function markerrel2(dx, dy) 
real dx, dy 

integer function markerrel3(dx, dy, dz) 
real dx, dy, dz 


integer function iRoveabs2(x, y) 
real x, y 

integer function moveabs3(x, y, z) 
real x, y, z 


integer function moverel2(dx, dy) 
real dx, dy 


integer function moverel3(dx, dy, dz) 
real dx, dy, dz 

integer function newframe() 

integer function polygonabs2(xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 

integer function polygonabsS(xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarray(*) 
integer n 


integer function polygonrel2(dxarray, dyarray, n) 
real dxarray(*), dyarray(*) 
integer n 
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integer function polygonrol3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 


integer function polylineabs2(xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 


integer function polylineabs3(xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarrayf*) 
integer n 


integer function polylinerel2(dxarray, dyarray, n) 
real dxarray(*), dyarray(*) 
integer n 

integer function polylinerol3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray (*) 
integer n 


integer function polymarkerabs2(xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 


integer function polymarkerabs3(xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarray{*) 
integer n 


integer function polyinarkerrGl2(dxarray, dyarray, n) 
real dxarray(*), dyarray(*) 
integer n 


integer function polyinarkerrel3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 


integer function printerror(message, errornum) 
character*(*) message 
integer errornxm 

integer function putraster(raster) 
integer raster(4) 


integer function rastertofile(raster, map, rasfid, 
integer raster(4) 

Integer map(3) 
integer rasfid, n 


n) 
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integer function renameretainseg(segname, newname) 
integer segname, newname 

integer function reportrecenterr (errornum) 
integer errornum 


integer function restoresegment(segname, filename) 
integer segname 
character*(*) filename 

integer function savesegment(segname, filename) 
integer segname 
character*(*) filename 

integer function selectvwsurf(surfacename) 
integer sur facename(*) 

Integer function setbackclip(onoff) 
integer onoff 

integer function setcharjust(just) 
integer just 

integer function setcharpath2(dx, dy) 
real dx, dy 

integer function setcharpathS(dx, dy, dz) 
real dx, dy, dz 

integer function setcharprecision(charprecision) 
integer charprecision 


integer function setcharsize(charwidth, charheight) 
real charwidth, charheight 

integer function setcharspace(charspace) 
real charspaco 

integer function setcharup2(dx, dy) 
real dx, dy 


integer function setcharup3(dx, dy, dz) 
real dx, dy, dz 


integer function setcoordsystype(type) 
integer type 
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integer function setdetectability(detectability) 
integer detect abi1ity 

integer function sotdrag(mode) 

Integer mode 

integer function setecho(dovicoclass, devicenum, echotype) 
integer deviceclass, devicentim, echotype 

integer function sotechogroup(deviceclass, devicenumarray, n, echotype) 
integer deviceclass, devicenumarray(*), n, echotype 


integer function setechoposition(deviceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
rea1 echox, echoy 



integer function setechosurface(deviceclass, devicentim, surfacename) 
integer deviceclass, devicenum 
integer surfacename(*) 

integer function sotfillindex(index) 
integer index 

integer function sotfont(font) 
integer font 


integer function setfrontclip(onoff) 
integer onoff 


integer function sethighlighting(highlighting) 
integer highlighting 

integer function setimgtransform2(sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 


integer function setimgtransformS(sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function setimgxformtype(type) 
integer type 

integer function setimgtranslate2(tx, ty) 
real tx, ty 

integer function setimgtranslate3(tx, ty, tz) 
real tx, ty, tz 
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Integer function setkeyboard(keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character*(*) initstring 
integer initcursor 


Integer function setlightdirect(dx, dy, dz) 
real dx, dy, dz 

integer function setlineindex(index) 
integer index 


integer function setlinestyle(linestyle) 
integer linestyle 

integer function setlinewidth(linewidth) 
real linewidth 


integer function setlocator2(locatornum, x, y) 
integer locatornum 
real x, y 

integer function setmarkersymbol(symbol) 
integer symbol 

integer function setndcspace2(width, height) 
real width, height 

integer function setndcspaceS(width, height, depth) 
real width, height, depth 

integer function setoutputclip(onoff) 
integer ono f f 

integer function setpen(pen) 
integer pen 

integer function setpick(picknum, aperture) 
integer picknum 
real aperture 

integer function setpickid(pickid) 
integer pickid 

integer function setpolyedgestyle(stylo) 
integer stylo 
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integer function setpolyintrstyle(style) 
integer style 



integer function setprimattribs(primattr) 
integer primattr (28) 


Note: The actual argument in the calling program corresponding to primattr should be an array 
which can be referenced both as a real array and as an integer array in order to acceis both 
integer valued and real valued primitive attributes. This can be done using the equivalence 
statement. 


integer function setprojection(projection^ dxproj, dyproj, dzproj) 

integer projection 

real dxproj, dyproj, dzproj 

integer function setrasterop(rop) 
integer rop 

integer function setsegdetectable(segname, detectability) 
integer segname, detectability 


integer function setseghighlight(segname, highlighting) 
integer segname, highlighting 


integer function setsegimgxform2(segname, sx, sy, a« tx, ty) 

integer segname 

real sx, sy, a, tx, ty 



Integer function setsegimgxform3(segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function setsegimgxlate2(segname, tx, ty) 
integer segname 
real tx, ty 

integer function setsegimgxlateS(segname, tx, ty, tz) 
integer segname 
real tx, ty, tz 

integer function setsegvisibility(segname, visibility) 
integer segname, visibility 

integer function setshadingparams(ambient, diffuse, specular, flood, buiq), hue, sty 
real ambient, diffuse, specular, flood, bump 
integer hue, style 
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integer function setstroke(strokenum, buffersize, distance, time) 
integer strokenum, buffersize 
real distance 
integer time 


integer function settextindex(index) 
integer index 


integer function setvaluator(valuatornum, initialvalue, lov, high) 

integer valuatornum 

real initialvaluo, low, high 


integer function setvertexindices(colorindexlist, n) 
integer colorindexlist (*), n 

integer function setvertexnormals(xlist, ylist, zlist, n) 
real xlist(*), ylist(*), zlist(*) 
integer n 

integer function setviewdepth(frontdistanco, backdistance) 
real frontdistance, backdistance 


integer function setvievplanedist(distance) 
real distance 


integer function sGtviewplanenorm(dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 


integer function setviewport2(xmin, xmax, ymln, ymax) 
real xmin, xmax, ymin, ymax 

integer function setviewport3(xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 

integer function setviewrefpoint(x, y, z) 
real x, y, z 

integer function setvievup2(dx, dy) 
real dx, dy 

integer function setviewup3(dx, dy, dz) 
real dx, dy, dz 

integer function setviewingparams(vievparams) 
real vievparams(26) 
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Note: The actual argument in the calling program corresponding to viewparams should be an 
array which can be referenced both as a real array and as an integer array in order to access 
both integer valued and real valued viewing parameters. This can be done using the 
equivalence statement. 

integer function setvisibility(visibility) 
integer visibility 



integer function setwindow(umin, umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function setwindowclip(onoff) 
integer onoff 

integer function setworldmatrix2(array) 
real array(3,3) 

integer function setworldmatrixS(array) 
real array(4,4) 

integer function setzbuffercut(surfacename, xlist, zlist, n) 
integer surfacename(*) 
real xlist(*), zllst(*) 
integer n 

o 

integer function sizeraster(surfacename, xmin, xmax, ymin, ymax, raster) 
integer sur facename(*) 
real xmin, xmax, ymin, ymax 
integer raster(4) 


integer function terminatecore() 

integer function terminatedevice(deviceclass, devicenum) 
integer deviceclass, devicenum 


integer function terminatevwsurf(surfacename) 
integer sur facename (*) 

integer function text(string) 
character*(*) string 
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All functions provided in SunCore may be called from Pascal programs by linking them with 
the /u9r/lib/libcorepa9,a library by using the Pascal compiler with a command line of the form: 

tutorial% pc —o grab grab.p —leorepas —Icore —Isunwlndow —Iplxrect —Im 

where grab»p is the Pascal source program. Note that l\i9rHib/libcore»a must be linked with 
the program (the —Icore option), and /u9r/l{b/ltbcorepa9,a must come before it (the — Icore- 
pas option). 


E.l. Programming Requirements 

The files typedef9pa9*h, n9ercorepa9,h, devincpa9»h and 9unpa9.k from the 
fu9rf{nchdelpa9cal directory must be included in the user’s source code to provide the neces¬ 
sary declarations for the Pascal interface to SunCore. Pascal programs which call SunCore 
functions must place these include files in the most global declaration section of the program: 

procp'am exan^le (input,output:) 

#includo */^s^"/ind'^de/pascal/typedefspas .h’ 

#includo */^®^/^^d^^®/P®scal/usercorepas .h* 

var 

{user declarations}- 

#include ’/^s*"/include/pascal/devincpas .h* 

#include '/usr/include/pascal/sunpas.h' 

If the Pascal program is composed of separately compiled files, these include statements must be 
in each Pascal file which uses SunCore functions and the corresponding defined constants. 
Defined constants for SunCore (see section on U9efut Con9tant9 in the introduction to this 
manual) are set in the file /u9r/include/pa9ca{/u9eTcorepa9,h, The default primitive attribute 
structure PRIMATTS provided in u9ercore.k and described in the section describing 
set^prtmitive_attribute9 is not provided in u9€rcorepa9.h. 

The Sun release of Pascal does not support the passing of variable length arrays as arguments in 
function or procedure calls. Therefore, fixed length arrays which are compatible with the 
SunCore-Pascal interface are declared as predefined types in the typedef9pa9»h file (see the 
Declarationa section of this appendix). The length of these arrays in 256. The length of 
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character strings passed from Pascal programs to SunCore must also be 256 characters. 

In the Sun release of Pascal, function names may not contain the underline character (J, There¬ 
fore, Pascal programs use abbreviated names to call the corresponding SunCore functions. The 
correspondence between the full SunCore names and the Pascal names appears in the Filnction 
Declarations section of this appendix. To provide a mechanism for returning the status of calls 
to SunCore routines, all SunCore routines must be called as functions from Pascal. Finally, 
although most SunCore functions use floats (32-bit reals), Pascal uses 64-bit reals. However, the 
Pascal programmer is only required to provide reals. SunCore functions which have structures 
as their arguments have corresponding predefined types in Pascal (see the Type Declarations 
section of this appendix). 

E.1,1. Routines Using View Surface Names 

View surface names in SunCore are structures containing pointers to device driver routines. 
The device driver names are supplied by the include file devincpas»h. The user may then simply 
use one of these names: 

bwldd for the Sun-1 monochrome display, 

bw2dd for the Sun-2 monochrome display, 

cgldd for the Sun-1 color display, 

cg2dd for the Sun-2 color display, 

pixwindd for windows on the Sun-1 monochrome display, 

cgpixwindd for windows on a color display. 


The pasloc function (provided in the SunCore-Pascal interface) transforms the function 
corresponding to the device driver into an integer which can then be inserted in the appropriate 
place in the device driver structure (see following example). 


CCode 

Pascal Code 

struct vvsurf dsurf = NULL_VWSURF; 

var 

int bwldd () ; 

dsur f:vwsur f; 

♦ 

tstr;vwsur fst; 

♦ 

tstr 

dsurf.dd = bwldd; 

dsurf.dd := pasloc(bwldd); 
dsur f.screenname := tstr; 
dsurf.windowname tstr; 

dsurf.windowfd := 0; 
dsurf.instance := 0; 
dsur f.cmapsize := 0; 
dsurf.cmapname := tstr; 
dsurf.flags := 0; 
dsurf.ptr := 0; 

initialize_view_surface(&dsurf, FALSE); 

X := InitializeVwsurf(dsurf, FALSE); 


Assigning a literal string of two spaces (blanks) to the tstr variable will initialize the character 
array to all spaces. 
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E.1.2. Routines Using Rasters and Colormaps 

For uses of SunCore functions which have rasters or colormaps as arguments which do not 
involve arithmetic direct manipulation by the programmer (for example, writing a raster to a 
file), the following restrictions on the functions do not apply and the programmer is only required 
to call the function. SunCore raster and colormap structures contain pointers to variable 
length data (that is, dynamic arrays). The SunCore-Pascal interface declares these varaibles as 
integers. 

Pascal programmers wishing to alter the contents of the colormap or raster data within a pro- 
gram can write a C function which uses the pointer value returned in Pascal to copy the infor¬ 
mation into a fixed-length array. Arithmetic operations can then be performed on the data using 
conventional Pascal statements. The programmer can then write another C function to copy 
the information back into the array pointed to by the pointer returned by the SunCore-Pascal 
interface. These C functions are not provided because the size of the fixed-length array will 
vary greatly among different applications. Therefore, the individual Pascal programmer must 
decide how large an array to declare for each application. 


E,2. Example Program 

The use of the SunCore-Pascal interface is illustrated by showing the text of a program for 
drawing the martini glass used in previous tutorial examples. 
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program martiniglass (input,output); 

#includ 0 '/^s*"/iriciud 0 /pasca 1/usercorepas .h*; 
#includ 0 */^s*'/iJf'clude/pascal/typedefspas .h' ; 


var 

glassdx, glassdy: parr •Ctyp 0 parr is an array of reals of 

length 256 declared in typedefs.h}; 

X;integer; 
dsur f:vwsur f; 
tstr:vsurfst; 

function sleep(x:integer):integer; external; 

#include '/^sr/include/pascal/sunpas.h'; 

#include */'J^s*"/iriclude/pascal/devincpas.h* ; 


procedure loaddata; 
begin 

glassdx [1] 
glassdx [2] 
glassdx [3] 
glassdx[4] 
glassdx[5] 
glassdx[6] 
glassdx[7] 
glassdx [8] 
glassdx[9] 

end; 


-10.0; 

glassdy[l] := 0.0; 

9.0; 

glassdy[2] := 1.0; 

0.0; 

glassdy[3] := 19.0; 

-14.0; 

glassdy [4] := 15.0,\ 

30.0; 

glassdy [5] := 0.0; 

-14.0; 

glassdy[6] := —15.0 

0.0; 

glassdy[7] := —19.0; 

9.0; 

glassdy[8] ;= —1.0; 

-10.0; 

glassdy[9] := 0.0; 


begin -(main program} 
tstr := ' *; 

dsurf.screenname tstr; 

dsurf.windowname := tstr; 
dsurf.windowfd := 0; 
dsurf.dd := pasloc(bwldd); 
dsurf.instance := O; 
dsurf.cmapsize ;= 0; 
dsur f.cmapname := tstr; 
dsurf.flags ;= 0; 
dsur f.charptr := 0; 

if (initializecore(BASIC, NOINPUT, TWOD) <> O) then 
writeln (' error 1') 

else 

if (initializevwsurf(dsurf, FALSE) <> 0) then 
witeln (’ error 2') 
else 

if (selectvwsurf(dsurf) <> 0) then 
writeln (* error 3') 
else 

x := setviewport2(0.125, 0.875, 0.125, 0.75); 

X := setwindow(— 50.0, 50.0, —10.0, 80.0); 

X := createten^seg; 

X := moveabs2(0.0, 0.0); 

loaddata; 

X := polylinerel2(glassdx, glassdy,9); 
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end. 


X := moverel2 (—12.0, 33.0); 
X := linGrGl2(24.0, 0,0); 

X := closGtGnpsGg; 

X := sleep(lO); 

X := deselectvwsurf(dsurf); 
X := terminatecore; 
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E.3. Correspondence Between C Names and Pascal Names 


Correspondence Between O Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

allocate_raster 

await_any_button 

await_any_bu-tton_get:_locator_2 

await_any„but;ton_got:_valuator 

await_keyboard 

a1locateraster 
awaitanybutton 
awtbuttongotloc2 
awtbuttongetva1 
awaitkeyboard 

await_pick 
await_st:roke_2 
begin_batch_o f_upda'tes 
closo_retained_seginent 
c1ose_temporary_segment 

avaitpick 
avaitstroke2 
beginbatchupdato 
closeretainseg 
c1osetempseg 

creat:e_ret;ained_segTnent 
crea'to_temporary_segment: 
de fine_co1or_indices 
delebe^al l_retained_segiiients 
delet:e_retained_seginent 

createretainseg 
createtempseg 
de fcolorindices 
delallretainsegs 
de1retainsegment 

dese1ect_view_sur face 
end_batch_of_updates 
file_to_raster 
free_raster 
get_mouse__state 

dese1ectvwsur f 
endbatchupdate 
filetoraster 

freeraster 

getmousestate 

get„raster 
initialize_coro 
initialize_device 
initialize_viow_surface 
incjuire^char j ust 

getraster 

initializecore 

initializedevice 
initializevwsurf 
inqcharjust 

inquire_cha rp ath_2 

incpJiiro_charpath_3 

inquire_charprecision 

inquire_charsize 

inciuire_charspaco 

inqcharpath2 
inqcharpath3 
inqcharprecision 
inqcharsize 
inqcharspace 

inc[uire_charup_2 
inq[uire_charup_3 
in<juire_co lor^indices 
inciuire_current„position_2 
inquire_current_position_3 

inqcharup2 
inqcharup3 
inqcolorindices 
inqcurrpos2 
inqcurrpos3 

inq[uire_detectabi 1 ity 
incruire_echo 

inqdetectabi1ity 
inqecho 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

inquire_echo_position 
inquire_echo_sur face 
inquire_fill_index 

inqechoposition 
inqechosur face 
inqfillindex 

inquire_ font 
inquiro_highlighting 
inquire_image_trans formation_2 
inquire_image_trans formation_3 
inq[uire_image_tr ans f ormation_type 

inqfont 

inqhigh1ighting 
inqimgtrans form2 
inqimgtrans form3 
inqimgx formtype 

incpjiire_image_tr ans 1 ato_2 
incjuir e_image_tr ans 1 ate_3 
inc[uire_inverse_coinposite_iiiatrix 
inquire_keyboard 
inquire_line_index 

inqimgtranslate2 
inqimgtranslate3 
inqinvcompmatrix 
inqkeyboard 
inqlineindex 

inquire_linesty1o 
inquiro^linewidth 
inquire_locator_2 
inquire_marker_syiiibol 
inc[uire_ndc_space_2 

inq1inesty1e 
inqlinewidth 
inqlocator2 
inqmarkorsymbo1 
inqndcspace2 

inquire_ndc„space_3 

inquire_open_retained_seginent 

inquire_open_temporary_segment 

inquire_pen 

inquire_pick_id 

inqndcspace3 

inqopenretainseg 

inqopentempseg 

inqpen 

inqpickid 

inquire_polygon_edge_style 
inquire_polygon_interior_style 
inq[uire_primitive_attributes 
incjuire_pro j ection 
inquire_rasterop 

inqpolyedgestyle 
inqpolyintrstyle 
inqprimattribs 
inqproj ection 
inqrasterop 

inquire_retained_segment_names 
inquire_retained_seg]nent_sur faces 
inquire_seginent_detectability 
inquire_segment_highlighting 
incjuire_seginent_image_trans format ion_2 

inqretainsegname 
inqretainsegsur f 
inqsogdotectablo 
inqs e ghigh1ight 
inqsegimgx form2 

inq[uire_segment_image_trans format ion_3 
inc[uire_se gment_ima ge_t r ans f orma t i on_typ e 
inc[uiro_segment_image_translato_2 
inciuire_segment_image_tr ans 1 ate_3 
inquire_segment_visibi1ity 

inqsogimgx form3 
inqsegimgx frmtyp 
inqsegimgxlate2 
inqsegimgxlate3 
inqsegvisibility 

inc[uire_stroke 

ingstroke 


Revision F of 15 May 1985 


E-7 






Using SunCore with Pascal Programs 


SunCore Reference Manual 


Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

inqu ir o_t: ext _ext: 2 

inqt:©xtextent2 

inciuire_text_extent;_3 

incft ext ext ent 3 

incjuire^toxt^index 

inqtoxtindex 

inquire_valuator 

inqvaluator 

inqpaire_view_dept:h 

inqviewdepth 

inquire_view_p1ane_distance 

inqviewplanedist 

inquiro_view_p1ane_norma1 

inqviewp1anenorm 

inquire_view_re ference_point 

inqviewre fpoint 

inquire_view_up_2 

inqviowup2 

inquire_view_up_3 

inqviewup3 

incpjiire_viewing_con-trol_parameters 

inqvwgcntrIparms 

inquire_vieving_parametors 

inqvievingparams 

inq[uire_viewport:_2 

inqviewport2 

inqpjiire_viewport_3 

inqviewport3 

inquire^visibility 

inqvisibility 

inquiro_vindow 

inqwindow 

inc[uire_world_coordina't©_matrix_2 

inqvorldmatrix2 

incjuire_world_coordina1:o_ina'trix_3 

inqworIdmatrix3 

line_abs_2 

lineabs2 

line_abs_3 

lineabs3 

line_rel_2 

linerel2 

line_rel_3 

linerel3 

map_ndc_to_world_2 

mapndctoworld2 

niap_ndc_-to_wor 1 d_3 

mapndctowor1d3 

map^wor 1 d_t:o_ndc_2 

mapvorldtondc2 

map_wor1d_to_ndc_3 

mapworldtondc3 

ma rke r_abs_ 2 

markerabs2 

marker_abs_3 

markerabs3 

marker_rel_2 

markerral2 

marker_rel_3 

markerrel3 

move_abs_2 

moveabs2 

inove_abs_3 

moveabsS 

move_rol_2 

moverel2 

ffiove_rel_3 

moverel3 

new_frame 

nevframe 

polygon_abs_2 

polygonabs2 

polygon_abs_3 

polygonabs3 

polygon_rel_2 

polygonr©12 

polygon_re1_3 

polygonrel3 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

polyline_abs_2 
polyline_abs_3 
poly1ine_re1_2 
polyline_rel_3 
polymarker_abs_2 

polylineabs2 
polylineabs3 
polylinerel2 
polylinerel3 
polymarkerabs2 

polymarker_abs_3 
polymarker^re1_2 
polymarker_rel_3 
print_error 
put_raster 

polymarkerabs3 
polymarkerre12 
polymarkerre13 
printerror 
putrastor 

raster_to_file 
renaine_ret:ained_segment 
report_most_recent_error 
res‘tore_seginent 
save_segment 

rastertofile 

renameretainseg 

reportrecenterr 

restoresegment 

savesegment 

select_view_sur face 
set_b ack_p1ane_c1ipping 
set_charjust 
set_charpath_2 
set_charpath_3 

selectvwsurf 
setbackclip 
setcharjust 
setcharpath2 
setcharpathS 

5ot_charprecision 

set_charsize 

set^charspace 

set_charup_2 

set_charup_3 

setcharprecision 
setcharsize 
setcharspace 
setcharup2 
setcharup3 

set_coordinate_systeiii_t:ype 

set_detectabi1ity 

set_drag 

set_echo 

set_echo_group 

setcoordsystype 

setdetectability 

setdrag 

setecho 

setechogroup 

set_echo_posit;ion 
se‘t_echo_sur face 
set_ fi1l_index 
set_font 

set_ front_p1ane_c1ipping 

setechoposition 
setechosur face 
setfillindex 
setfont 
set frontc1ip 

set_highlighting 
set_imago_trans formation_2 
set_image_trans formation_3 
set_image_transformation_type 
set_iina<ye_tr ans 1 ate_2 

sethighlighting 
setimgtrans form2 
setimgtrans form3 
setimgx formtype 
set imcrtr ans 1 ate2 
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Correspondence Between C Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

set_ima go_trans1ato_3 

set_keyboard 

set_1ight_diraction 

set_1ine_index 

set_1inestyle 

sotimgtrans1ato3 
sotkeyboard 
sot1ightdiroct 
set1ineindex 
sot1inestyle 

set_linewidth 
set_locator_2 
set_inarker_syinbo 1 
set_ndc_spaco_2 
set_ndc_space_3 

set1inewidth 

setlocator2 
sotmarkersymbo1 
setndcspace2 
setndcspace3 

set_output_c1ipping 

set^pen 

set_pick 

set_pick_id 

set_polygon_edge_sty1e 

set_polygon_interior_stylo 

sotoutputc1ip 

setpen 

setpick 

setpickid 

setpolyedgesty1e 

setpolyintrstyle 

set_primitive_attributes 
set^proj action 
set_rasterop 

set_segment_detectability 
s e t _s a gment _h i gh 1 i ght in g 

setprimattribs 

setprojection 

sotrasterop 

setsegdetectable 

setseghighlight 

set_segment_image_transforination_2 
s et_se gment_image_tr ans formation_3 
set_segment_image_trans1ato_2 
set_segment_iinage_translate_3 
set_segment_visibi1ity 

setsegimgx form2 
setsegimgx form3 
setsegimgxlate2 
setsegimgx1ate3 
setsegvisibility 

set_shading_paranieters 
set_stroke 
set_text_index 
set_valuator 
set_vertex_indices 

setshadingparams 

setstroke 

settextindex 

setvaluator 

setvertexindices 

set_vertex_noriiia 1 s 
set_view_depth 
sat_view_p1ane_distance 
sat_view_p1ane_norma1 
sat_view_ro faronca^point 

setvertexnorma1s 
setvievdepth 
setvievp1anedist 
setvievp1anenorm 
sotviewrofpoint 

set_view_up_2 

set_view_up_3 

set_viewing_parameters 

set_viowport_2 

setvievup2 

setviewup3 

setviewingparams 

setviewport2 


E-10 


Revision F of 15 May 1985 









SunCore Reference Manual 


Using SunCore with Pascal Programs 


Correspondence Between G Names and Pascal Names 

SunCore Name 

Pascal Equivalent 

set_viewport_3 

setviewportS 

set_visibility 

set^window 

s et_window_c1ipping 

set:_world_coordinat:e_matrix_2 

set:_wor ld_coordinate_matrix_3 

setvisibi1ity 
setwindow 
setwindowc1ip 
setvorldmatrix2 
setworldmatrix3 

set_zbuf fer^cut 
size_raster 
terminate_core 
terminate_devico 
terminate_view_sur face 

text 

setzbuf fercut 

sizeraster 
terminatecore 
terminatedevice 
terminatevwsur f 
puttext 



o 
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E.4. Declarations for SunCore-Pascal Interface 



Type Declarations 


type larr — array[1..256] of integer; 

type parr = array[1..256] of real; 

type cct = array[1..257] of char; 

type ivarray = array[1..4^1..4] of real; 

type ivarrayl = array[1..3,1.,3] of real; 

type pttype = record 

x,y,z,w:real; 

end; 


type aspect = record 

width, height:real; 
end; 



type primattr = record 

lineindx: integer; 
fillindx: integer; 
textindx: integer; 
linestyl; integer; 
polyintstyl: integer; 
polyedgsty1: integer; 
linwidth: real; 
pen: integer; 
font: integer; 
charsize: aspect; 

chrup, chrpath, chrspace: pttype; 
chj ust: integer; 
chqualty: integer; 
marker: integer; 
pickid: integer; 
rasterop: integer; 
end; 
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type rasttyp = record 

width: Integer; 
height: integer; 
depth: integer; 
bits: integer; {var} 
end; 


type cmap = record 

typ: integer; 
nbyt: integer; 
dat :integer; {var} 
end; 


type windtype = record 


end; 


xmin, xmax, ymin, ymax:real; 


type porttype = record 

end; 


xmin«xmax, ymin, ymax, zmin, zmax: real; 



type vwprmtype = record 

vwrefpt: array [1..3] of real; 
vwplnorm: array [l.,3] of real; 
viewdis:real; 
frontdis:real; 
backdis:real; 
projtype:integer; 
projdir: array [1..3] of real; 
window:windtype; 
vwupdir: array [1..3] of real; 
viewport:porttype; 
end; 


type vwsurf = record 

screenname: array [1..DEVNAMESIZE] of char; 

windowname: array [1..DEVNAMESIZE] of char; 

windowfd:integer; 

dd:integer; 

instance:integer; 

cmapsize:integer; 

cmapname: array [1. .DEVNAMESIZE] of char; 
flags:integer; 
ptr: integer; 

end; 



typo vwsurfst = array [1..DEVNAMESIZE] of char; 
type vwarr = array[1. .MA3CVSURF] of vwsurf; 
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E.4-S- Function Declarations 


function allocateraster(var rptr:rasttyp):Integer; external; 

function avaitanybutton(tim:integer; 

var buttonnum:integer);integer; external; 


function awtbuttongetloc2(time:integer; locatornum:Integer; 

var buttonnum:integer; var x:real; 
var y:real):integer; external; 


function awtbuttongetval(time:integer; valnum:integer; 

var buttonnum:integer; var valrreal): 
integer; externa1; 


function awaitkeyboard(tim:integer;keynum:integer;var sptr;cct; 

var length:integer):integer; external; 


function awaitpick(time:integer; picknxim:integer; 

var segnam:integer; var pickid:Integer) 
:integer; external; 


function awaitstroke2(tim:integor;picknum:integor;asizo:integer;var x:parr; 

var y;parr;numxy:integer):integer; external; 


function beginbatchupdate:integer; external; 


function closeretalnseg:integer; external; 


function closeten^sseg:integer; external; 


function createretainseg(segname:integer):integer; external; 

function createtempseg:integer; external; 

function defcolorindices(surfacename:vwsurf; 

i1:integer;i2:integer; 

var r:parr;var g;parr;var b:parr 

):integer; external; 

function delaHretainsegs:integer; external; 

function delretainsegment(segname:integer):Integer; external; 
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function dese1ectvwsurf(surfacename:vwsurf 

):Integer; external; 

function endbatchupdate:integer; external; 

function filetoraster(rasfid:integer;var rptr:rasttyp; 

var map:cmap):integer; external; 

function freeraster(var rptr:rasttyp):integer; external; 

function getmousestate(var devclass: int; var devnum: int; var xireal; 

var y:real;var buttons:integer): 
integer; external; 

function getraster(surfacename rvwsurf; 

xmin:real;xmax:real;ymin:real;ymax:real; 

xd:integer;yd:integer;var rptr:rasttyp):integer; 

external; 

function initializecore(outputlevel:integer; 

inputlevel:integer; 

dimension:integer):integer; external; 

function initializedevice(deviceclass:integer; 

devicenum:integer):integer; external; 

function initializevwsurf(surfacename:vwsurf; typ:integer 

);integer; external; 

function inqcharjust(var chjust:integer):integer; external; 

function inqcharpath2(var x:real;var y:real):integer; external; 

function inqcharpathS(var x:real;var y:real;var z:real):integer; external; 

function inqcharprecision(var chquality:integer):integer; external; 

function inqcharsize(var width:real;var height:real):integer; external; 

function inqcharspace(var space:real):integer; external; 

function inqcharup2(var x:real;var y:real):integer; external; 

function inqcharupS(var x:real;var y:real;var z:real):integer; external; 
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function inqcolorindices(surfacenaino:vwsurf; 

il:integer;i2:integer; 

var r:parr;var g:parr;var biparr 

):integer; external; 

function inqcurrpos2(var x:real;var y:real);Integer; external; 

function inqcurrpos3(var x;real;var y:real;var z:real):integer; external; 

function inqdetectability(var detect:integer):integer; external; 

function inqecho(devclass:integer;dovnum:integer; 

var echotypo:integer):integer; external; 


function inqechoposition(devclass:integer;devnum:integer; 

var x:real;var y:real):integer; external; 


function inqechosurface(devclass:integer;devnxim:integer; 

var surfacename;vwsurf)rinteger; external; 

function inqfillindex(var color:integer):integer; external; 

function inqfont(var font:integer):integer; external; 

function inqhighlighting(var highlight:integer):integer; external; 

function inqimgtransforni2(var sx:real; var sy:real;var a:real 

;var tx:real; var ty:real 
):integer; external; 

function inqimgtransforms(var sx:real; var sy:real;var szrreal 

;var ax:real; var ay:real;var az;real 
;var tx:real; var ty:real;var tz:real 
):integer; external; 

function inqimgxformtype(var segtype:integer):integer; external; 

function inqimgtranslate2(var tx:real; var ty;real):integer; external; 

function inqimgtranslate3(var tx:real; var ty:real;var tz:real 

):integer; external; 

function inqinvcompmatrix(var iarrayrivarray):integer; external; 
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function inqkeyboard(keynum:Integer;var bufslze:integer;var string:cct; 

var pos:integer):integer; external; 

function inqlineindex(var color;integer);integer; external; 

function inqlinestyle(var linestyle:integer):integer; external; 

function inqlinewidth(var linewidth:real):integer; external; 

function inqlocator2(locnum;integer; 

var x:real;var y:real):integer; external; 

function inqmarkersymbol(var mark:integer);integer; external; 

function inqndcspace2(var width:real;var height:real) rinteger; external; 

function inqndcspaceS(var width:real;var height:real;var 

depth:real):integer; external; 

function inqopenrotainseg(var segname:integer):integer; external; 

function inqopenten^seg(var open:integer):integer; external; 

function inqpen(var pen:integer):integer; external; 

function inqpickid(var pick:integer):integer; external; 

function inqpolyedgestyle(var pestyle:integer):integer; external; 

function inqpolyintrstyle(var pistyle:integer):integer; external; 

function inqprimattribs(var defprim:primattr):integer; external; 

function inqprojection (var ptype:integer; var dx:real; var dy:real; 

var dz:real):integer; external; 

function inqrasterop(var rastop:integer):integer; external; 

function inqretainsegname(arraycnt:integer; var seglist:iarr; 

var segcnt:integer):integer; external; 

function inqretainsegsurf(segname:integer; arraycnt:integer; var surflist:vwarr 

var surfcnt:integer):integer; external; 
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Note: since vwarr is an array of MAXVSURF viewsnrfaees, arrayeni should he MAXVSURF . 

function inqsegdotectable(segname:integer;var dtablo:integer) 

:integer; external; 

function inqseghighlight(segname:Integer;var highlIght:integer) 

:integer; external; 



function inqsegimgxform2(segname:integer;var sx:real;var sy:real; 

var a:real;var tx:real;var ty:real 
):integer; external; 


function inqsegimgx form3(segname;integer;var sx;real;var sy;real; 

var sz;real;var rx;real;var ry:real; 

var rz:real;var tx;real;var ty;real;var tz:real 

):integer; external; 

function inqsegimgxfrmtyp(segname:integer;var segtype:integer) 

;integer; external; 


function inqsegimgxlate2(segname:integer;var tx:real;var ty:real) 

:integer; external; 


function inqsegimgxlateS(segname;integer;var sx;real;var sy:real; 

var sz:real):integer; external; 



function inqsegvisibility(segname;integer;var visible;integer); 

integer; external; 

function inqstroke(strokenum:integer;var bufsize;integer;var 

dist:real;var time;integer):integer; external; 


function inqtextextent2(var string:cct;var dx:real; var dy;real 

);integer; external; 

function inqtextextenta (var string;cct;var dxireal; var dy;real 

; var dz:real);integer; external; 

function inqtextindex(var color:integer);integer; external; 

function inqvaluator(valnum;Integer;var init;real;var low;real;var high;real) 

:integer; external; 

function inqviewdepth(var fdist:real;var bdist:real) 

:integer; external; 
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function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 

function 


inqyievplanedist(var vdist:real):integer; external; 


inqviewplanenorin(var dx:real; var dyrreal; 

var dz:rea1):integer; externa1; 


incjviewrefpoint(var rx:real; var ryireal; 

var rz:real):integer; external; 


inqviewup2(var dx:real; var dy:real 

):integer; external; 

inqviewup3(var dx:real; var dy;real; 

var dz:real):integer; external; 


intjvwgcntrlparms (var wclip: integer; var fclip: integer; 

var bclip:integer;var typiinteger) 

:integer; external; 

inqviewingparams(var viewparm;wprmtype):integer; external; 


inqviewport2(var xmin:real; var xmax;real;var ymin:real;var ymaxtreal 

):integer; external; 

inqpriewportS(var xminireal; var xmax:real;var ymin:real;var ymaxireal 

;var zmin:real;var zmax:real) 

:integer; external; 


inqvisibility(var visible:integer) 

:integer; external; 

inqp»^indow(var umin:real; var umax:real;var vmin:real;var vmax:real 

):integer; external; 

inqworldmatrix2(var iarray:ivarrayl)linteger; external; 
inqworldmatrix3(var iarray:ivarray):integer; external; 
lineabs2(x:real;y:real):integer; external; 
lineabs3(x:real;y:real;z:real):integer; external; 
linerel2(x:real;y:real):integer; external; 
linerel3(x:real;y:real;z:real):integer; external; 
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function mapndctoworld2(ndx:real; ndytroal; 

var wldx:real; var wldyrreal) 

:integer; externa1; 

function mapndctovorld3 (ndx:real; ndy:real; ndz:real; 

var wldxrreal; var wldyrreal 
; var wldzrreal) 

:integer; externa1; 

function mapworldtondc2(wldxrreal; wldyrreal; 

var ndxrreal; var ndyrreal) 
rinteger; externa1; 

function mapworldtondcS(wldxrreal; wldyrreal; wldzrreal; 

var ndxrreal; var ndyrreal 
; var ndzrreal 

) rinteger; external; 

function markerabs2(mxrreal;myrreal)rinteger; external; 

function markerabs3(mxrreal; ray:real;mzrreal)rinteger; external; 

function markerrel2(dxrreal;dyrreal)rinteger; external; 

function markerrel3(dx r real; dy r real;dz r real)rinteger; external; 

function moveabs2(xrreal;yrreal) rinteger; external; 

function moveabs3(xrreal;yrreal;zrreal)rInteger; external; 

function moverel2(xrreal;yrreal) rinteger; external; 

function moverel3(xrreal;yrreal; 2 rreal):integer; external; 

function newframerinteger; external; 

function pasloc(function frinteger 

):integer; external; 

function polygonabs2(var xcoorrparr; var ycoorrparr; 

nr integer):integer; external; 

function polygonabsS(var xcoorrparr; var ycoorrparr;var zcoortparr; 
n:integer):integer; external; 
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function polygonrel2(var xcoor:parr; var ycoor:parr; 

n:integer):integer; external; 

function polygonrel3 (var xcoor:parr; var ycoor:parr;var zcoorrparr; 
n:integer):integer; external; 


function polylineabs2(var xcooriparr; var ycoor:parr; 

n:integer):integer; external; 


function polylineabs3(var xcoor;parr; var ycoor:parr;var zcoorrparr; 
n:integer):integer; external; 


function polylinerel2(var xcoorrparr;var ycoorrparr; 

n:integer):integer; external; 

function polylinerel3(var xcoorrparr; var ycoorrparr;var zcoorrparr; 
n rinteger)rinteger; external; 

function polymarkerabs2(var xcoorrparr; var ycoorrparr; 
n:integer) rinteger; external; 


function polymarkerabsS(var xcoorrparr; var ycoorrparr;var zcoorrparr; 
nr integer)rinteger; external; 

function polyinarkerrel2(var xcoorrparr; var ycoorrparr; 

n;integer):integer; external; 

function polymarkerrel3 (var xcoorrparr; var ycoorrparr;var zcoorrparr; 
n:integer)rinteger; external; 

function printerror(var stringrcct;errorrinteger)rinteger; external; 

function putraster(var rptrrrasttyp):integer; external; 

function puttext(var stringrcct)rinteger; external; 

function rastertofile(var rptrrrasttyp;var map remap;rasfidrinteger 

):integer; external; 

function renameretainseg(segrname rinteger;newname:integer)rinteger; external; 

function reportrecenterr(var error rinteger):integer; external; 

function restoresegmont(segname rinteger;var fnamo r cct)rinteger; external; 
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function savesegment(segname:integer;var fname:cct):integer; external; 

function selectvwsurf(surfacename:vwsurf 

);integer; external; 

function sotbackclip(onoff:integer):integer; external; 

function setcharjust(chjust:integer):integer; external; 

function setcharpath2(dx:real; dy:real):integer; external; 

function setcharpathS(dx:real; dy:real;dz:real):integer; external; 

function setcharprecision(chquality:integer):integer; external; 

function setcharsize(chwid:real;chht:real):integer; external; 

function setcharspace(space:real):integer; external; 

function setcharup2(dx:real; dy:real);integer; external; 

function setcharup3(dx:real; dy:real;dz:real):integer; external; 

function setcoordsystype(typ:integer):integer; external; 

function setdetectability(detect:integer):integer; external; 

function setdrag(drag:integer):integer; external; 

function setccho(devclass:integer;devnum:integer; 

echotype:integer):integer; external; 

function setechogroup(devclass:integer;var devarray:iarr;n:integer; 

echotype:integer):integer; external; 

function setechoposition(devclass:integer;devnum:integer; 

x:real;y:real)linteger; external; 

function setechosurface(devclass:integer;devnum:integer; 

surfacenamo:vwsurf);integer; external; 

function setfillindex(color:integer):integer; external; 
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function setfont(font:integer):Integer; external; 

function setfrontclip(onoff:integer):integer; external; 

function sethighlighting(highlight:integer):integer; external; 

function setimgtransform2(sx:real; sy:real;a:real 

;tx:real; ty:roal);integer; external; 

function setimgtransforms(sx:real; sy:real;sz:real; 

ax:real; ay;real;az:real; 
tx:roal; ty:real;tz:real) 

;integer; external; 

function setimgxformtype(segtype:integer):integer; external; 

function setimgtrans1ate2(tx:real; ty:real):integer; external; 

function setimgtranslateS(txireal; ty:real;tz:real):integer; external; 

function setkeyboard(keynum:integer;bufsize:integer;var string:cct; 

pos:integer):integer; external; 

function setlightdirect(dx:real; dy:real;dz:real 

):integer; external; 

function setlineindex(color:integer):integer; external; 
function setlinestyle(style:integer):integer; external; 
function setlinewidth(width:real):integer; external; 

function setlocator2(locnum;integer;x:real;y:real):integer; external; 

function setmarkersymbol(mark:integer):integer; external; 

function setndcspace2(width:real;height:real):integer; external; 

function setndcspaceS(width:real;height:real;depth:real) 

;integer; external; 

function setoutputclip(onoff:integer):integer; external; 
function setpen(pen:integer):integer; external; 
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function setpick(picknum;integer; aperture: real):integer; external; 


function setpickid(pickid:integer):integer; external; 


function setpolyedgestyle(pestyle:integer):integer; external; 
function setpolyintrstyle(pistyle:integer):integer; external; 


function setprimattribs(var defprim:primattr):integer; external; 


function setprojection(ptype:integer;dx:real; dy:real;dz;real) 

:integer; external; 

function setrasterop(rop:integer):integer; external; 

function setsegdetectable(segname:Integer; detectbl:integer) 

:integer; external; 

function setseghighlight(segname:integer; highlight:integer) 

:integer; external; 


function setsegimgxform2(segname:integer;sx:real; sy:real;a:real; 

tx:real;ty:real):integer; external; 


function setsegimgxforms(segname:integer; sx:real; syireal; 

sz:real; rx:real; ryrreal; rz:real 
; tx:real; tyrreal; tzrreal 
):integer; external; 


function setsegimgx1ate2(segname:integer;tx:real; ty:real 

):integer; external; 

function setsegimgxlateS(segname:integer;tx:real; ty:real;tz:real 

):integer; external; 

function setsegYisibility(segneuae: Integer; visible .‘integer) : integer; external; 


function setshadingparams(arab:real;dif:real;spec:real;flood:real; 

bun^:real;hue:integer;style:integer 
):integer; external; 

function setstroke(strokenum:integer;bufsize:integer; 

dist:real;time:integer) 

:integer; external; 


E-24 


Revision F of 15 May 1985 




SunCore Reference Manual Using SunCore with Pascal Programs 

function settextlndex(color:Integer):Integer; external; 

function setvaluator(valnum:integer;init:real;low:real;high:real) 

:integer; externa1; 

function setvertexindicos(var x:larr;n:integer):integer; external; 

function setvertexnormals(var xcooriparr; var ycoor:parr;var zcooriparr; 
n:integer):integer; external; 

function setviewdepth(near:real;far:real):integer; external; 

function setviewplanedist(dist:real)linteger; external; 

function setviewplanenorm(dx:real; dy:real;dz:real):integer; external; 

function setviewrefpoint(x:real; y:real;z:real):integer; external; 

function setviewup2(dx:real; dyrreal):integer; external; 

function setviewup3(dx:real; dy:real;dz:real):integer; external; 

function setviewingparams(var viewparm:vwprmtype):integer; external; 

function setviewport2 (xmin:real;xmax:real;ymin:real;ymax:real): 

integer; external; 

function setviewportS (xmin: real; xmax: real ;yinin: real ;yinax: real; zmin :roal; zmax:real) 
:integer; external; 

function setvisibility(visibility:integer):integer; external; 

function setwindow (ximin: real; xmax: real;vmin: real;vmax: real) 

:integer; external; 

function setwindowclip(onoff:integer):integer; external; 

function setworldinatrix2(var iarray:ivarrayl):integer; external; 

function setworldmatrixS(var iarray:ivarray):integer; external; 

function setzbuffercut(var surfacename:vwsurf;var x:parr; 
var z:parr;n:integer):integer; external; 
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function sizeraster(var surfacename:wsurf; 

xmin:rea1;xmax:real;ymin:rea1;ymax:rea1; 
var rptrrrasttyp):integer; external; 

function terminatecoro;integer; external; 

function terminatedevicafdevclass:Integer;devnum:integer):integer; external; 


function terminatovwsurf(var surfacenametvwsurf) :integer; external; 
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Appendix F 

Higher Performance SunCore Library 



SunCore programs which are to be run on machines with Sun’s hardware floating point option 
may use an alternative SunCore library which provides higher floating point performance. This 
library is in Insr/lihlUhcoTtsky.a. A program linked with this library will only run on a machine 
with hardware floating point. 

To use this library for C programs, use a C compiler command line like: 

tutorial% cc —fsky —e grab grab.c —Icoresl^ —Isunvindow —Ipixrect —In 

and to use this library for Fortran programs: 

tutorial% £77 —fs^ —o grab grab*£ —lcora77 —Icoreal^ —launwindow —Iplxrect —In 

Note that this library cannot be used with Pascal programs in the current release. 

If compiling and linking are done in separate steps, the —f oky option must also be specified in 
the linking stage. The —fsky option may also be used in the compiling step. See the cc(l) and 
/77(1) manual pages for details. 
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Appendix G 


SunCore Error Numbers 


SunCore does not use the error numbers suggested by the ACM CORE standard. The following 
table matches an error number with the error message: 


Error 

Number 

Deeeription 

0 

The CORE SYSTEM has already been initialized. 

1 

The specified level cannot be supported. 

2 

The surface has already been initialized. 

3 

No physical surface is associated with the specified logical surface. 

4 

The CORE SYSTEM has not been initialized. 

5 

The specified surface has not been initialized. 

6 

The specified surface is already selected. 

7 

The specified surface was not selected. 

8 

A segment is open. 

9 

The specified surface is not selected. 

10 

The specified surface has not been deselected. 

11 

This function has already been called once. 

12 

A segment has been opened. 

13 

A value specified for a default attribute is improper. 

14 

The specified segment does not exist. 

15 

The VIEW SURFACE ARRAY is not large enough. 

16 

Segment list overflow, can’t create segment. 

17 

There has been no ‘end batch’ since last ‘begin batch’. 

18 

There has been no corresponding ‘begin batch’. 

19 

A viewing function has been invoked, or a segment has been created. 

20 

The value for TYPE is improper. 

21 

No segment is open. 

22 

n is <*» 0. 

23 

String contains an illegal character. 

24 

The vectors established by CHARSPACE and CHARUP are parallel. 

25 

Invalid marker table offset. 

28 

Invocation when no open segment. 

27 

Invalid attribute value. 

28 

Invalid segment tvpe. 
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Error 

Number 


De4cription 


29 

30 

31 

32 

33 

34 

35 

36 

37 
33 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 

61 

62 

63 

64 

65 

66 

67 


Invalid segment number. 

Invalid image transformation for the segment. 

A retained segment named SEGNAME already exists. 

The segment type is inconsistent with the current 1MAGE_TRANSF0RM. 
No view surface is currently selected. 

The current viewing specification is inconsistent. 

No view surfaces have been initialized. 

There is an existing retained segment named NEWJ^AME. 

There is no retained segment named SEGMENT^NAME. 

No characters in string (n—0), 

Dx, dy, and dz, are all zero: no direction can be established. 

MIN is not less than MAX, for u or v bounds. 

FRONT_DISTANCE exceeds BACKJDISTANCE; back clip 
plane is in front. 

‘ndc5p2’ or ‘ndcsp3’ has been invoked since SunCore was last initialized. 
The invocation of ‘ndcspx’ is too late, default values have been assumed. 
A parameter value is greater than 1, or is less than or equal to 0. 

Neither parameter has a value of 1. 

Viewport extent is outside of normalized device coordinate space. 

MIN is not less than MAX, for x, y, or z bounds. 

Specified device already enabled. 

DEVICE^CLASS or DEVICEJWM invalid. 

DEVICE^CLASS invalid. 

Specified device is not enabled. 

LOCATORJsrUM is invalid. 

The specified LOCATOR device is not enabled. 

VALUATOR_NUM is invalid. 

The specified VALUATOR device is not enabled. 

The TIME value is less than zero. 

EVENT_CLASS and EVENT_NUM do not specify a valid event device. 
EVENT_CLASS is not a legal event device class. 

The specified association already exists. 

EVENT_CLASS or SAMPLED.CLASS reference invalid or 
wrong type of class. 

EVENT_NUM or SAMRLED_NUM are invalid device numbers 
for their classes. 

The specified association does not exists. 

The current event report is not from a PICK device. 

The current event report is not from a KEYBOARD event. 

Input string was not large enough to hold the string centered by user. 
\\^en event occurred, the LOCATOR device was not enabled or was 
not associated with the event device. 

When event occurred, the VALUATOR device was not enabled or was 
not associated with the event device. 
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Error 

Number 


Description 

XECHO and YECHO specify positions outside NDC space. 
PICK_NUM does not specify a valid PICK device. 

LOCATORJWM does not specify a valid LOCATOR device. 
XLOC, YLOC specify a position outside normalized device 
coordinate space. 

VALUATORJ'JUM is not a valid VALUATOR device. 
LOWJVALUE is greater than fflGH_VALUE, 

INITIAL^VALUE lies outside the range defined by 
LOW.VALUE and fflGH_VALUE, 

KEYBOARDJWM is not a valid KEYBOARD device. 
BUFFER^SIZE is <= zero or > the defined maximum. 
BUTTON_NUM is not a valid BUTTON device. 

Incorrect arguments for the specified function. 

Incorrect argument count for the specified function. 

Specified function not supported. 

More than MAXPOLY vertices in polygon. 

Invalid Viewing Specification. Viewing Matrix Unchanged! 
Invalid view surface name. 

Selected view surface cannot support hidden surfaces. 

No other view surface can be initialized at this time. 
Raster depth is 1 or 8 bit pixels only. 

Unable to allocate space for virtual memory display list. 
Memory allocation failure. 

Error in view reference point. 


Error 

Error 

Error 

Error 

Error 


in view plane normal, 
in view plane distance, 
in view depth, 
in projection, 
in window. 


Error in view up direction. 

Error in viewport. 

Set_ndc^pace_2 or set__ndc_space_3 has already been invoked. 
The default NDC space has already been established. 

A parameter is not in the range of 0 to 1. 

Neither width nor height has a value of 1. 

Width or height is 0. 

STROKE_NUM is not a valid STROKE device. 

Input device is already initialized. 

Input device is not initialized. 

DEIVICE_CLASS is not a valid device class. 

Invalid echo type for PICK device. 

Invalid echo type for KEYBOARD device. 

Invalid echo type for STROKE device. 

Invalid echo type for LOCATOR device. 
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Deocription 

110 

Invalid echo type for VALUATOR device. 

111 

Invalid echo type for BUTTON device. 

112 

Echo position specified is outside NDO space. 

113 

No BUTTON device is initialized. 
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READER COMMENT SHEET 


Dear Customer, 

t ' 

We who work here at Sun Microsystems wish to provide the best possible documentation for our 
products. To this end, we solicit your comments on this manual. We would appreciate your tel¬ 
ling us about errors in the content of the manual, and about any material which you feel should 
be there but isn’t. 


Typographical Errors; 

Please list typographical Errors by page number and actual text of the error. 


o 

Technical Errors; 

Please list errors of fact by page number and actual text of the error. 


Content; 

Did this guide meet your needs? If not, please indicate what you think should be added 
or deleted in order to do so. Please comment on any material which you feel should be 
present but is not. Is there material which is in other manuals, but would be more con¬ 
venient if it were in this manual? 



Layout and Style; 

Did you find the organization of this guide useful? If not, how would you rearrange 
things? Do yon find the style of this manual pleasing or irritating? What would you like 
to see different? 
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